Generate an organized multi-file OpenAPI repository.
You! Hello. Do you need to write or contribute to an OpenAPI definition? If so, read on...
We recommend a docs-like-code approach to OpenAPI definitions:
There are a few advantages in hosting your API definition on GitHub:
There are also some advantages to a multi-file YAML format OpenAPI definition:
This generator helps to create a GitHub repo with the following features:
You will have a structure similar to this:
├── .redocly.yaml ├── LICENSE ├── README.md ├── docs │ ├── favicon.png │ └── index.html ├── openapi │ ├── README.md │ ├── code_samples │ │ ├── C# │ │ │ └── echo │ │ │ └── post.cs │ │ ├── PHP │ │ │ └── echo │ │ │ └── post.php │ │ └── README.md │ ├── components │ │ └── README.md │ └── paths │ └── README.md └── package.json
However, you can adjust it to any structure you prefer.
openapi folder is where your OpenAPI definition will live. Inside there, and the sub-folders, there are
README.md files to help guide you further. This is also where your entrypoint
openapi.yaml will live.
components folder is where you will organize sub-folders such as
schema to define your schema.
paths folder is where you will organize your paths. There will be a 'README.md' file in there with suggestions for how to organize it into specially named files (or folders) that use an
@ in place of a
/ (because files cannot have a
/ character in them). You will also be able to use path parameters by wrapping them in curly braces
.redocly.yaml file is a universal configuration for various Redocly tools including the lint tool and reference doc engine.
The generated repository includes installing a dependency for our
openapi-cli tool which supports commands such as
bundle, and more. There are scripted shortcuts defined in the repository's
We assume you already have node.js installed.
npm install -g create-openapi-repo
npx in this example. However, remove
npx if you installed it globally.
You will be presented with some questions. You can create a new definition or use an existing definition to initialize your project.
Please note, if you do start a new one, remember to create a GitHub repo where your OpenAPI definition will live.
If you use the prior version of this generated repository, please read the following upgrade instructions.
Migrate your repository from a previous structure of OpenAPI repo to this newer structure with our migration tool.
Run this in the root folder of your repo.
npx create-openapi-repo --migrate-2-3
Note: the migration tool does not migrate plugins automatically. You would need to manually add them to the
Thank you for wanting to support us. Here are some ideas how to support us: