Last updated 1 month ago

Multi-file OpenAPI definitions

We recommend a multi-file OpenAPI definition.

Skills you will need:

  • General knowledge of the OpenAPI Specification 3.0.3.
  • How to use $refs.

Why

Be able to explain the reasons for using a multi-file format:

  1. Easier to contribute.
  2. Easier to review contributions.
  3. Better supports a docs-like-code workflow.
  4. Enforces better re-use of objects to avoid duplication and divergence issues.
  5. Supported by Redocly toolchain including the free open-source openapi-cli.

Be able to explain the drawbacks of a multi-file approach:

  1. Some tools don't support $refs in other files. Mitigation: openapi-cli has a bundle command, and Redocly has a free API Registry to build a bundled file which can be useful for others.

Folder structure

We have built a free tool, create-openapi-repo, that can take an OpenAPI 3 definition and convert it to a multi-file format. It also works when you are starting from scratch without any definition.

When you create the repo npx create-openapi-repo and follow the instructions, you'll end up with files structured like this inside of the openapi folder:

├── README.md
├── code_samples
│   ├── C#
│   │   └── echo
│   │       └── post.cs
│   ├── PHP
│   │   └── echo
│   │       └── post.php
│   └── README.md
├── components
│   ├── README.md
│   ├── headers
│   │   └── ExpiresAfter.yaml
│   ├── schemas
│   │   ├── Email.yaml
│   │   └── User.yaml
│   └── securitySchemes
│       ├── api_key.yaml
│       ├── basic_auth.yaml
│       └── main_auth.yaml
├── openapi.yaml
└── paths
    ├── README.md
    ├── echo.yaml
    └── users@{username}.yaml

There is a README.md in each directory with further instructions and suggestions.

You'll notice the main openapi.yaml file which we call the root document of the OpenAPI definition.

Keep in mind, this is just one possible structure. Structure the files however you want, and you will still benefit from the tools the repository installs, mainly the Redocly openapi-cli tool.

Inspect the package.json file to learn more about these scripts.

Root file

The openapi.yaml file referred to above is what we call the root file. This file can be named anything, but you may need to adjust the .redocly.yaml file if you rename it.

In this example, we rename the file from openapi.yaml to foo.yaml and also rename the within the .redocly.yaml file the corresponding apiDefinitions section. The main could be renamed to any unique alias. The alias can be useful when you have multiple definitions, you can refer to them on the command line like: openapi validate main.

# See https://docs.redoc.ly/cli/configuration/ for more information.
apiDefinitions:
  main: "openapi/foo.yaml"
lint:
  rules:
    no-unused-schemas: warning
referenceDocs:
  htmlTemplate: ./docs/index.html
  theme:
    colors:
      primary: "#32329f"

The root openapi.yaml file looks like this:

openapi: 3.0.3
info:
  version: 1.0.0
  title: Example.com
  termsOfService: 'https://example.com/terms/'
  contact:
    email: contact@example.com
    url: 'http://example.com/contact'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  x-logo:
    url: 'https://apis.guru/openapi-template/logo.png'
  description: >
    This is an **example** API to demonstrate features of OpenAPI specification.

    # Introduction

    Truncated intentionally...

externalDocs:
  description: Find out how to create a GitHub repo for your OpenAPI definition.
  url: 'https://github.com/Rebilly/generator-openapi-repo'
tags:
  - name: Echo
    description: Example echo operations
  - name: User
    description: Operations about user
servers:
  - url: 'http://example.com/api/v1'
  - url: 'https://example.com/api/v1'
paths:
  '/users/{username}':
    $ref: 'paths/users@{username}.yaml'
  /echo:
    $ref: paths/echo.yaml
components:
  securitySchemes:
    main_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'http://example.com/api/oauth/dialog'
          scopes:
            'read:users': read users info
            'write:users': modify or remove users
    api_key:
      type: apiKey
      in: header
      name: api_key
    basic_auth:
      type: http
      scheme: basic

This file is intentionally short. Most of the content is organized in the paths and components folders.

Validate

npmyarn
npm test
yarn test

Bundle

npmyarn
npm build
yarn build

Preview-docs

If you subscribe to our commercial offering, ask us for a license key, and your previews will be using Redocly API Reference (or it will fallback to Redoc community edition).

npmyarn
npm start
yarn start