Last updated

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 the sidebars.yaml file with your OpenAPI descriptions.

If you have many OpenAPI descriptions, you may want to add them using the catalog option under theme 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

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.
 
Next page