Generate your API Reference | Fern Documentation

Fern automatically generates your API Reference documentation from your OpenAPI Specification or Fern Definition. Once you’ve set up your API definition, adding it to your docs takes just one line of configuration.

Prerequisites

For OpenAPI/AsyncAPI: Add your spec file and create a generators.yml that references it in the api.specs section
For Fern Definition: Add a definition/ directory with your API definition files (Fern auto-detects this)

Learn more about project structure.

Add - api: API Reference to your navigation in docs.yml:

docs.yml

1 navigation:
2   - api: API Reference

Fern will automatically populate your endpoints, types, and code snippets from your API definition.

API Reference configuration options

Property	Value
`api` (required)	Title of the API Reference Section
`api-name`	Name of the API you’re referencing, if there are multiple APIs
`audiences`	List of audiences that determines which endpoints, schemas, and properties are displayed in your API Reference
`availability`	Set the availability status for the entire API Reference or specific sections
`display-errors`	Displays error schemas in the API References
`summary`	Relative path to the Markdown file; the summary is displayed at the top of the API section
`layout`	Customize the order that your API endpoints are displayed in the docs site
`icon`	Icon to display next to the API section in the navigation
`slug`	Customize the slug for the API section (by default, the slug is generated from the API title)
`skip-slug`	When `true`, skips the slug generation for the API section
`alphabetized`	When `true`, organizes all sections and endpoints in alphabetical order
`flattened`	Display all endpoints at the top level (hides the API Reference Section’s title)
`paginated`	Display all endpoints on separate pages (by default, endpoints are displayed on one single, long page)
`tag-description-pages`	When `true`, uses OpenAPI tag descriptions as summary pages for each section

More on customizing your API Reference here.

Include more than one API Reference

To include multiple, distinct API definitions in your documentation, use the api-name property. The api-name corresponds to the folder name containing your API definition.

This works with any combination of OpenAPI and Fern Definition formats. For example:

$ fern/
>   ├─ fern.config.json
>   ├─ docs.yml
>   ├─ plant-api/
>   │   ├─ openapi.yml       # OpenAPI spec
>   │   └─ generators.yml    # References the OpenAPI spec
>   └─ garden-api/
>       └─ definition/       # Fern Definition (auto-detected)
>           └─ api.yml

For a simple setup without tabs, you can include multiple API References directly in your navigation:

docs.yml

1 navigation:
2   - api: Plant Store
3     api-name: plant-api   # Matches folder name containing your API definition
4   - api: Garden
5     api-name: garden-api  # Matches folder name containing your API definition

When using tabs, each API Reference must be placed within a tab’s layout:

docs.yml

1 tabs:
2   plant-api:
3     display-name: Plant Store API
4     icon: leaf
5   garden-api:
6     display-name: Garden API
7     icon: tree
8 navigation:
9   - tab: plant-api  # References the tab defined above
10     layout:
11       - api: Plant Store API
12         api-name: plant-api  # Matches folder name containing your API definition
13         skip-slug: true
14   - tab: garden-api  # References the tab defined above
15     layout:
16       - api: Garden API
17         api-name: garden-api  # Matches folder name containing your API definition
18         skip-slug: true