How to load an OpenAPI description document with an external schema

[Alfred Myers (alfredmyers)]

Given the OpenAPI description document at https://www.bcb.gov.br/htms/dasfn/catalogo/1.0.10/openapi.json referencing the external schema file at https://www.bcb.gov.br/htms/dasfn/catalogo/1.0.10/schema.json, the following code

usingMicrosoft.OpenApi;usingMicrosoft.OpenApi.Reader;namespaceDasfn{internalclassProgram{staticasyncTaskMain(string[]args){UribaseUrl=new("https://www.bcb.gov.br/htms/dasfn/catalogo/1.0.10/");OpenApiReaderSettingssettings=new(){BaseUrl=baseUrl,LoadExternalRefs=true,};ReadResultreadResult=awaitOpenApiDocument.LoadAsync(newUri(baseUrl,"openapi.json").AbsoluteUri,settings);if(readResult.Diagnostic?.ErrorsisIList<OpenApiError>errors){foreach(OpenApiErrorerrorinerrors){Console.WriteLine(error);}}OpenApiDocumentdocument=readResult.Document!;OpenApiSchemaReferenceschema=(OpenApiSchemaReference)document.Paths["/catalogo"].Operations![HttpMethod.Get].Responses!["200"].Content!["application/json"].Schema!;Console.WriteLine($"Schema unresolved reference: {schema.UnresolvedReference}");}}}

... reports failure to load schema.json apparently due to it not having a Version field. Furthermore, the schema is marked as an unsolved reference:

[File: schema.json] Version node not found.
Schema unresolved reference: True

It is my understanding that Version is only required on the OpenAPI description itself and not on referenced schemas.

I have no control over the definition of this OpenAPI description document so changing it is not an option.

Is there a proper way or a workaround for loading the external schema?

[Alfred Myers (alfredmyers)]

I've got it working by patching the OpenAPI description document with a fragment containing the schema

usingMicrosoft.OpenApi;usingMicrosoft.OpenApi.Reader;usingSystem.Text.Json.Nodes;namespaceDasfn{internalclassProgram{staticasyncTaskMain(string[]args){UribaseUrl=new("https://www.bcb.gov.br/htms/dasfn/catalogo/1.0.10/");HttpClienthttpClient=new(){BaseAddress=baseUrl,};OpenApiReaderSettingssettings=new(){BaseUrl=baseUrl,HttpClient=httpClient,LoadExternalRefs=true,};(OpenApiDocument?document,OpenApiDiagnostic?diagnostic)=awaitOpenApiDocument.LoadAsync(newUri(baseUrl,"openapi.json").AbsoluteUri,settings);if(diagnostic?.ErrorsisIList<OpenApiError>errors){foreach(OpenApiErrorerrorinerrors){Console.WriteLine(error);}}OpenApiMediaTypemediaType=document!.Paths["/catalogo"].Operations![HttpMethod.Get].Responses!["200"].Content!["application/json"];if(mediaType.SchemaisOpenApiSchemaReferenceschemaReference&&schemaReference.UnresolvedReference){usingMemoryStreamstream=new(awaithttpClient.GetByteArrayAsync(schemaReference.Reference.ExternalResource,CancellationToken.None));mediaType.Schema=settings.Readers["json"].ReadFragment<OpenApiSchema>(stream,diagnostic!.SpecificationVersion,document,outOpenApiDiagnosticschemaDiagnostic);}}}}

There's probably a better/proper way to do this, but at least for now this will suffice.