An OpenAPI reader that merges external references into a single document for .NET using the [Microsoft OpenAPI](https://www.nuget.org/packages/Microsoft.OpenApi.readers) toolset
The class OpenApiMultiFileReader is used to load an OpenAPI specifications document file locally or remotely using a YAML or JSON file. OpenApiMultiFileReader will automatically merge external references if the OAS file uses them.
: External references must be in the same folder as the main OAS file or in subdirectories.
Local Files
Remote Files: When loading OAS files remotely, external references can be:
Relative URLs: components.yaml#/components/schemas/Pet (resolved relative to the main file's URL)
ReadResult result = await OpenApiMultiFileReader.Read("petstore.yaml");
OpenApiDocument document = result.OpenApiDocument;
Example with Local External References
In the example below, we have OpenAPI specifications that are split into multiple documents. petstore.yaml contains the paths and petstore.components.yaml contain the components/schemas
petstore.yaml
openapi: 3.0.3
paths:
/pet:
post:
tags:
- pet
summary: Add a new pet to the store
description: Add a new pet to the store
operationId: addPet
requestBody:
description: Create a new pet in the store
content:
application/json:
schema:
$ref: 'petstore.components.yaml#/components/schemas/Pet'
required: true
responses:
"200":
description: Successful operation
content:
application/json:
schema:
$ref: 'petstore.components.yaml#/components/schemas/Pet'
Example with Remote External References
You can also use remote external references with absolute URLs:
openapi: 3.0.3
paths:
/pet:
post:
tags:
- pet
summary: Add a new pet to the store
description: Add a new pet to the store
operationId: addPet
requestBody:
description: Create a new pet in the store
content:
application/json:
schema:
$ref: 'https://example.com/openapi/components.yaml#/components/schemas/Pet'
required: true
responses:
"200":
description: Successful operation
content:
application/json:
schema:
$ref: 'https://example.com/openapi/components.yaml#/components/schemas/Pet'
Or with relative URLs when the main file is also remote:
openapi: 3.0.3
paths:
/pet:
post:
requestBody:
content:
application/json:
schema:
$ref: 'components.yaml#/components/schemas/Pet' # Resolved relative to main file's URL
