Add OpenAPI descriptions
Transform your OpenAPI description YAML or JSON file into interactive documentation by adding it to your project. You can add one or multiple OpenAPI descriptions to your project.
Add OpenAPI descriptions to your project in one of two ways:
- Save files at root: If you have only one or two OpenAPI descriptions, save your OpenAPI description files at the root of your project.
- Use
sidebars.yaml
: If you have more than two OpenAPI description files, update thesidebars.yaml
file with your OpenAPI descriptions.
If you have many OpenAPI descriptions, you may want to add them using the catalog
option in your redocly.yaml
file. See Add a catalog for more information.
Before you begin
Make sure you have the following before you begin:
- finalized versions of your OpenAPI descriptions
Save description files at the root
If you only have one or two OpenAPI description files, and you do not have a sidebars.yaml
file in your project, to add an OpenAPI description to your project, place the files at the root of your project. Afterwards, the OpenAPI reference documentation is automatically added to your sidebar when you run your project.
Your file should be one of the supported OpenAPI specification versions. See Supported file types for more information.
If you have a sidebars.yaml
file in your project, adding your OpenAPI description to the root of your project does not add it to your sidebar automatically. You must add your OpenAPI description to your sidebars.yaml
file.
Use the sidebars.yaml file
If you have a sidebars.yaml
file in your project, you must add any files, including OpenAPI descriptions, you want displayed in your sidebar to it.
To add an OpenAPI file to your project with a sidebars.yaml
file, add the page
and label
keys with the corresponding values for the OpenAPI description to your sidebars.yaml
file, as in the following example:
- page: sample-api.yaml label: Sample API
Use the group
key for multiple descriptions
If you have multiple OpenAPI descriptions, you may want to use a group
key for each description so that the different endpoints are only revealed when selected.
To add multiple OpenAPI descriptions using group
keys, update your sidebars.yaml
file as in the following example:
- group: Sample product 1 API items: - page: sample-api-1.yaml label: Sample product 1 API - group: Sample product 2 API items: - page: sample-product-2.yaml label: Sample product 2 API
Related how-tos
- Organize multiple API descriptions by Adding a catalog
- Help users find your content by Configuring navigation in the sidebar
Resources
- See the Replay the API explorer concept doc to learn more about making your API reference docs interactive.
- Use OpenAPI extensions in your API description to produce richer documentation.
- Check out the OpenAPI configuration reference to learn more about the configuration options you can apply to customize your OpenAPI description reference docs.