Bundling Multi-File OpenAPI Documents into a Single File

Featured image for sharing metadata for article

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
  title: Example API
  version: '0.1.0'
      description: Do something
                $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": [
  "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.

Written by Jamie Tanna's profile image Jamie Tanna on , and last updated on .

Content for this article is shared under the terms of the Creative Commons Attribution Non Commercial Share Alike 4.0 International, and code is shared under the Apache License 2.0.

#blogumentation #openapi #command-line.

Also on:

This post was filed under articles.

Interactions with this post

Interactions with this post

Below you can find the interactions that this page has had using WebMention.

Have you written a response to this post? Let me know the URL:

Do you not have a website set up with WebMention capabilities? You can use Comment Parade.