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
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;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'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 URLpetstore.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: categoryFor 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 ☕
