Skip to content

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.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish