OpenAPI documents can get pretty large, especially when you're documenting all the various API request and response entities. To simplify this, we can split it into multiple files, and use $refs to "include" the other files.

However, as I found with creating a client-side OpenAPI viewer, splitting files down makes it difficult when tools aren't able to resolve the $refs themselves.

Fortunately, there are tools around that can help us bundle OpenAPI documents into a single file.

Because I'm building a few APIs from scratch at the moment, I can use OpenAPI 3.1.0, but it turns out that not all the tools we would want to use are possible.

For instance, the official swagger-codegen-cli does not yet support OpenAPI 3.1.0.

Another top hit on that StackOverflow is Speccy, which is no longer supported.

Example spec

Let's take the following, fairly minimal OpenAPI 3.1.0 example:

openapi: 3.1.0
info:
  title: Example API
  version: '0.1.0'
paths:
  "/":
    get:
      description: Do something
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: './response.json'

Which then has response.json:

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "Response object",
  "description": "The more descriptive name for the Response Object spec",
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "$comment": "The name of the API",
      "type": "string"
    }
  },
  "additionalProperties": false
}

Using @redocly/openapi-cli

Redocly's openapi CLI tool allows us to run i.e.:

npx @redocly/openapi-cli@latest bundle openapi.yml > out.yml

Which then creates a single out.yml which has all our document bundled.