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.

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.

1
navigation: 
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.

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

Ordering section contents

1
navigation: 
2
  - api: API Reference
3
    layout: 
4
      - user: 
5
          - POST /user
6
          - PUT /user/{username}
7
          - DELETE /user/{username}

Customizing the API Reference

Renaming sections

By default, section display names come from service file names (Fern Definition) or tag names (OpenAPI) in your spec.

To override the display name of a section, use the section property in your docs.yml and reference the lowerCamelCase version of the original service file name (Fern Definition) or tag name (OpenAPI) in referenced-packages.

1
navigation: 
2
  - api: API Reference
3
    layout:
4
      - section: "Billing" # New section display name
5
        referenced-packages: 
6
          - billing # lowerCamelCase version of original tag/service file name from your spec
7
        contents: []
8
      - section: "Bank Accounts"
9
        referenced-packages: 
10
          - bankAccounts
11
        contents: []

Flattening sections

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

1
navigation: 
2
  - api: API Reference
3
    flattened: true

Styling endpoints

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

1
navigation: 
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}

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.

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

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), availability, and contents.

1
navigation: 
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

Adding a section overview

You can add overview pages to your API Reference or individual sections in two ways:

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

1
navigation:
2
  - api: API Reference
3
    tag-description-pages: true

Adding pages and links

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

1
navigation: 
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

Adding availability

You can set the availability for the entire API Reference or for specific sections. Options are: stable, generally-available, in-development, pre-release, deprecated, or beta.

1
navigation: 
2
  - api: API Reference
3
    availability: generally-available
4
    layout: 
5
      - section: My Section
6
        availability: beta
7
        icon: flower
8
        contents: 
9
        # endpoints here

When you set availability for a section, all endpoints in that section will inherit the section-level availability unless explicitly overridden in your API definition.

Displaying endpoint errors

Set display-errors to true to show error schemas on endpoint pages. The error names, status codes, and response objects are pulled from your API definition.

1
navigation:
2
  - api: API Reference
3
    display-errors: true

Clicking on an error expands it to show the error name, code, and object returned. The response also updates to show the error object.

Configuration options reference

The following properties can be set on the - api entry in your docs.yml navigation.