Bundle a multi-file OpenAPI description into one file
Last checked and updated
A description split over several files is easier to review and to reuse; some code generators, gateways and documentation tools read only one file. Bundling turns the first into the second: apigit bundle openapi.yaml follows every $ref to another file, moves the target into the root document and rewrites the reference to point there.
A description in four files
openapi.yaml
paths/order.yaml
schemas/order.yaml
schemas/user.yaml
The root refers to a path item, which refers to a schema, which refers to another:
# openapi.yaml
paths:
/orders/{orderId}:
$ref: "./paths/order.yaml"
# paths/order.yaml
get:
operationId: getOrder
responses:
"200":
description: The order
content:
application/json:
schema:
$ref: "../schemas/order.yaml"
# schemas/order.yaml
type: object
required: [id, buyer]
properties:
id:
type: string
buyer:
$ref: "./user.yaml"
Each relative path starts at the file it is written in: ../schemas/order.yaml from paths/, ./user.yaml from schemas/.
The bundle
$ apigit bundle openapi.yaml
paths:
/orders/{orderId}:
get:
operationId: getOrder
...
responses:
"200":
description: The order
content:
application/json:
schema:
$ref: "#/components/schemas/order"
components:
schemas:
user:
type: object
...
order:
type: object
required:
- id
- buyer
properties:
id:
type: string
buyer:
$ref: "#/components/schemas/user"
Three things happened. The path item was inlined. Each schema file became an entry under components/schemas, named after its file (order.yaml became order), and the references now point inside the document. Schemas stay shared: user exists once, however many places refer to it.
-o bundled.yaml writes to a file, --ext json writes JSON, and --dereference also replaces the internal references with copies, for the few tools that cannot follow any $ref.
Since file names become schema names, and schema names usually become type names in generated code, name the files as you want the types to be called: Order.yaml if you want Order.
Lint the bundle
Linting the root of this split description reports an error that the bundle does not have (output shortened to that finding):
$ apigit lint openapi.yaml
...
12:21 error oas3-schema "~1orders~1{orderId}" property must not have unevaluated properties. (paths./orders/{orderId})
$ apigit bundle openapi.yaml -o bundled.yaml && apigit lint bundled.yaml
2:6 warn info-contact Info object must have "contact" object. (info)
1 problem (0 errors, 1 warning, 0 info, 0 hints)
The description is valid: a path item may be a $ref in OpenAPI 3.1. The linter stumbles on the external path-item reference in an OpenAPI 3.1 document: with the path item written inline and only the schemas in other files there is no error, and the same four files declared as 3.0.3 lint without it. After bundling there is no such reference. In CI, bundle first and lint the result, which is also what downstream tools will read.
A mock server reads the split files directly:
$ apigit mock serve openapi.yaml --port 4653
$ curl http://127.0.0.1:4653/orders/1
{"id":"string","buyer":{"id":"string","email":"user@example.com"}}
When bundling fails
error: bundle failed: Can't resolve $ref: ENOENT: no such file or directory '<path>' at #/paths/~1orders~1{orderId} means a reference points to a file that does not exist; for a missing target inside a file the message is Can't resolve $ref at <pointer>. The pointer in the message is the place of the reference, with / written as ~1: finding a broken $ref.