API References

Customize API Reference layout

When you include an API in your docs.yml file, you can customize how the endpoints and sections are displayed in the sidebar navigation. By default, the reference will generate a navigation hierarchy based on the structure of the API spec, but several customizations can be configured.

API Sections

If you are using an OpenAPI Specification, sections are created based on the tags property, converted to lowerCamelCase convention (e.g., createUser). If you are using a Fern Definition, sections are created based on the service file names.

If you would like to only display a subset of endpoints, read more about the Audiences property for OpenAPI Specifications or Fern Definitions.

Ordering the API Reference

Alphabetizing endpoints and sections

To sort all sections and endpoints alphabetically, unless explicitly ordered in layout, set alphabetized to true.

docs.yml
1navigation: 
2  - api: API Reference
3    alphabetized: true

Ordering top-level sections

The layout option allows you to specify the order of sub-packages, sections, endpoints, and pages at the top level of your API Reference.

docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - POST /user
5      - user
6      - store
7      - plant
Ordered API Reference

Ordering section contents

Adding a : after the section name allows you to specify the order of its nested sub-packages and endpoints.

Referencing Endpoints

To reference an endpoint, you can use either:

  • METHOD /path/name (best for OpenAPI Specification)
  • serviceName.endpointName (best for Fern Definition)

You can reference an endpoint using the format METHOD /path.

docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - user: 
5          - POST /user
6          - PUT /user/{username}
7          - DELETE /user/{username}
Content ordered in the API Reference

Customizing the API Reference

Flattening sections

To remove the API Reference title and display the section contents, set flattened to true.

docs.yml
1navigation: 
2  - api: API Reference
3    flattened: true
Flattened API Reference

Styling endpoints

To customize the display of an endpoint, you can add a title. You can also use slug to customize the endpoint URL.

docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - user: 
5          - endpoint: POST /user
6            title: Create a User
7            slug: user-creation
8          - DELETE /user/{username}
Setting an endpoint title

Hiding endpoints

You can hide an endpoint from the API reference by setting hidden to true. The endpoint will still be accessible at its URL.

docs.yml
1navigation: 
2  - api: API Reference
3    paginated: true
4    layout: 
5      - user: 
6          - endpoint: POST /user
7            title: Create a User
8            slug: user-creation
9          - endpoint: DELETE /user/{username}
10            hidden: true
Fully hidden endpoints

For best results, API References with hidden endpoints should use the paginated: true configuration to avoid discovering endpoints from long-scrolling.

Adding custom sections

You can add arbitrary folders in the sidebar by adding a section to your API Reference layout. A section can comprise entire groups of endpoints, individual endpoints, or even just Markdown pages. Sections can be customized by adding properties like a icon, summary, slug (or skip-slug), and contents.

docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - section: My Section
5        icon: flower
6        contents: 
7          - PUT /user/{username}
8          - plant
9          - plantInfo # tag names are converted to camelCase convention
Custom section in the API Reference

Adding a section overview

The summary property allows you to add an .md or .mdx page as an overview of the API Reference or a section.

docs.yml
1navigation: 
2  - api: API Reference
3    summary: pages/api-overview.mdx
4    layout: 
5      - user: 
6          summary: pages/user-overview.mdx
API Reference with a summary page

You can add regular pages and external links within your API Reference.

docs.yml
1navigation: 
2  - api: API Reference
3    layout: 
4      - user: 
5          contents: 
6            - page: User Guide
7              path: ./docs/pages/user-guide.mdx
8            - link: Link Title
9              href: http://google.com

Disable long-scrolling

By default, the API Reference renders all endpoints on a single page (long-scrolling). To create separate pages for each endpoint, set paginated: true.

docs.yml
1navigation: 
2  - api: API Reference
3    paginated: true