Transform an OpenAPI description in YAML or JSON into interactive reference documentation by adding it to your project. You can add one or more descriptions.
Make sure you have an OpenAPI description file in YAML or JSON format. All versions of OpenAPI are supported.
Place the OpenAPI description file anywhere in your project, either at the root or in a folder. When you run your project, the file is detected automatically and served as reference documentation with its own sidebar. The sidebar is generated from the tags and operations in the description. No extra configuration is required.
For example, add apis/sample-api.yaml, then open /apis/sample-api to see the generated reference.
The API reference's URL path matches the location of its OpenAPI description file in your project, with the file extension removed. For example, apis/museum.yaml is served at /apis/museum.
To change the URL, rename or move the OpenAPI description file to the path you want it served from. For more information, see file-based routing.
The reference is served at its own URL and has its own automatically generated sidebar. It's reachable as soon as you add it, with no navigation configuration required.
To help people find it, link to it from wherever you want. For example, add it to the navbar with a page that points at the OpenAPI file:
navbar:
items:
- page: apis/sample-api.yaml
label: Sample APIYou can also link to it from an in-page text link, a card, or an API catalog.
To place the reference inside a custom sidebar alongside your other content, with control over its order and grouping, add it to a sidebars.yaml file:
- group: Sample product 1 API
items:
- page: apis/sample-product-1.yaml
label: Sample product 1 API
- group: Sample product 2 API
items:
- page: apis/sample-product-2.yaml
label: Sample product 2 APIFor all available options, see Sidebar configuration.
- Sidebar configuration - Organize and customize the sidebar navigation for your API references and other content
- Navbar configuration - Add top-level links to your API references and other pages
- API catalog configuration - Showcase multiple REST, GraphQL, and AsyncAPI descriptions together in a catalog
- Replay API explorer - Learn about the interactive API testing features used in reference documentation
- OpenAPI extensions - Use custom extensions to create richer, more detailed reference documentation
- OpenAPI configuration reference - Customize how OpenAPI descriptions are rendered, styled, and behave