{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"multi-file-openapi-definitions","__idx":0},"children":["Multi-file OpenAPI definitions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend a multi-file OpenAPI definition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Skills you will need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["General knowledge of the OpenAPI Specification 3.0.3."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How to ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/ref-guide"},"children":["use $refs"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why","__idx":1},"children":["Why"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Be able to explain the reasons for using a multi-file format:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Easier to contribute."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Easier to review contributions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Better supports a docs-like-code workflow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enforces better re-use of objects to avoid duplication and divergence issues."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Supported by Redocly toolchain including the free open-source ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/redocly/redocly-cli"},"children":["Redocly CLI"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Be able to explain the drawbacks of a multi-file approach:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some tools don't support ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"s in other files. Mitigation: Redocly CLI has a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bundle"]}," command, and Redocly has a free API Registry to build a bundled file which can be useful for others."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Tip"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Redocly's ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://marketplace.visualstudio.com/items?itemName=Redocly.openapi-vs-code"},"children":["VS Code plugin"]}," to lint as you type. Navigate to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]},"s with a click or keystroke."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"folder-structure","__idx":2},"children":["Folder structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We have built a free tool, Redocly CLI ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/commands/split"},"children":["split command"]},", that can take an OpenAPI 3 definition and convert it to a multi-file format. If you are starting from scratch without any definition, you can use our template ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/Redocly/openapi-starter"},"children":["OpenAPI starter repo"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll end up with files structured like this inside of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi"]}," folder:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"├── README.md\n├── code_samples\n│   ├── C#\n│   │   └── echo\n│   │       └── post.cs\n│   ├── PHP\n│   │   └── echo\n│   │       └── post.php\n│   └── README.md\n├── components\n│   ├── README.md\n│   ├── headers\n│   │   └── ExpiresAfter.yaml\n│   ├── schemas\n│   │   ├── Email.yaml\n│   │   └── User.yaml\n│   └── securitySchemes\n│       ├── api_key.yaml\n│       ├── basic_auth.yaml\n│       └── main_auth.yaml\n├── openapi.yaml\n└── paths\n    ├── README.md\n    ├── echo.yaml\n    └── users@{username}.yaml\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["README.md"]}," in each directory with further instructions and suggestions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll notice the main ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi.yaml"]}," file which we call the root document of the OpenAPI definition."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep in mind, this is just one possible structure. Structure the files however you want, and you will still benefit from Redocly's CLI tool."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inspect the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.json"]}," file to learn more about these scripts."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"root-file","__idx":3},"children":["Root file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/configuration"},"children":["Redocly configuration file"]}," if you rename it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, we rename the file from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi.yaml"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["foo.yaml"]}," and also rename the within the configuration file the corresponding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," object's properties."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["foo@v1"]}," 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: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly lint foo@v1"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# See https://redocly.com/docs/cli/configuration/ for more information.\napis:\n  foo@v1:\n    root: \"openapi/foo.yaml\"\nrules:\n  no-unused-schemas: warning\ntheme:\n  openapi:\n    htmlTemplate: ./docs/index.html\n    theme:\n      colors:\n        primary: \"#32329f\"\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The root ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi.yaml"]}," file looks like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"openapi: 3.0.3\ninfo:\n  version: 1.0.0\n  title: Example.com\n  termsOfService: 'https://example.com/terms/'\n  contact:\n    email: contact@example.com\n    url: 'http://example.com/contact'\n  license:\n    name: Apache 2.0\n    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'\n  x-logo:\n    url: 'https://apis.guru/openapi-template/logo.png'\n  description: >\n    This is an **example** API to demonstrate features of OpenAPI specification.\n\n    # Introduction\n\n    Truncated intentionally...\n\nexternalDocs:\n  description: Find out how to create a GitHub repo for your OpenAPI definition.\n  url: 'https://github.com/Rebilly/generator-openapi-repo'\ntags:\n  - name: Echo\n    description: Example echo operations\n  - name: User\n    description: Operations about user\nservers:\n  - url: 'http://example.com/api/v1'\n  - url: 'https://example.com/api/v1'\npaths:\n  '/users/{username}':\n    $ref: 'paths/users@{username}.yaml'\n  /echo:\n    $ref: paths/echo.yaml\ncomponents:\n  securitySchemes:\n    main_auth:\n      type: oauth2\n      flows:\n        implicit:\n          authorizationUrl: 'http://example.com/api/oauth/dialog'\n          scopes:\n            'read:users': read users info\n            'write:users': modify or remove users\n    api_key:\n      type: apiKey\n      in: header\n      name: api_key\n    basic_auth:\n      type: http\n      scheme: basic\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This file is intentionally short."," ","Most of the content is organized in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components"]}," folders."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"lint","__idx":4},"children":["Lint"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"npm","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"npm test\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"yarn","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"yarn test\n","lang":"shell"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bundle","__idx":5},"children":["Bundle"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"npm","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"npm build\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"yarn","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"yarn build\n","lang":"shell"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"preview-docs","__idx":6},"children":["Preview-docs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you subscribe to our commercial offering, generate an API key under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["My profile"]},", and your previews will be using Redocly API docs (or it will fallback to Redoc community edition)."," ","Read more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/v1/commands/preview-docs"},"children":["preview-docs"]},"."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"npm","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"npm start\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"yarn","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"yarn start\n","lang":"shell"},"children":[]}]}]}]},"frontmatter":{},"tagList":["admonition","tab","tabs"],"title":"Multi-file OpenAPI definitions","lastModified":"2025-07-25T04:49:53.000Z"}