OasReader 3.7.0.20

Build NuGet Quality Gate Status codecov

Multi Document Reader for OpenAPI.NET

An OpenAPI reader that merges external references into a single document using the Microsoft OpenAPI toolset.

This is based on the work done by Jan Kokenberg and contains source code from the dotnet-openapi-merger CLI tool

Usage

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.

Local Files: External references must be in the same folder as the main OAS file or in subdirectories.

Remote Files: When loading OAS files remotely, external references can be:

• Absolute URLs: https://example.com/components.yaml#/components/schemas/Pet
• 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

petstore.components.yaml

openapi: 3.0.3
components:
 schemas:
 Pet:
 required:
 - name
 - photoUrls
 type: object
 properties:
 id:
 type: integer
 format: int64
 example: 10
 name:
 type: string
 example: doggie
 category:
 $ref: '#/components/schemas/Category'
 photoUrls:
 type: array
 xml:
 wrapped: true
 items:
 type: string
 xml:
 name: photoUrl
 tags:
 type: array
 xml:
 wrapped: true
 items:
 $ref: '#/components/schemas/Tag'
 status:
 type: string
 description: pet status in the store
 enum:
 - available
 - pending
 - sold
 Category:
 type: object
 properties:
 id:
 type: integer
 format: int64
 example: 1
 name:
 type: string
 example: Dogs
 xml:
 name: category

For tips and tricks on software development, check out my blog

If you find this useful and feel a bit generous then feel free to buy me a coffee ☕