Generate your API Reference

A key benefit of using Fern Docs is that once you’ve defined your API, you get your API Reference documentation with just one line. Add - api: API Reference to your navigation in docs.yml and Fern takes care of the rest! You’ll see your endpoints, types, and cURL snippets automatically populated from your OpenAPI Specification or Fern Definition.

Example:

docs.yml
1navigation:
2 - api: API Reference

API Reference configuration options

PropertyValue
api (required)Title of the API Reference Section
api-nameName of the API we are referencing, if there are multiple APIs
audiencesList of audiences that determines which endpoints, schemas, and properties are displayed in your API Reference
display-errorsDisplays error schemas in the API References
snippetsEnable generated SDK code snippets in your API Reference
summaryRelative path to the Markdown file; the summary is displayed at the top of the API section
layoutCustomize the order that your API endpoints are displayed in the docs site
iconIcon to display next to the API section in the navigation
slugCustomize the slug for the API section (by default, the slug is generated from the API title)
skip-slugWhen true, skips the slug generation for the API section
alphabetizedWhen true, organizes all sections and endpoints in alphabetical order
flattenedDisplay all endpoints at the top level (hides the API Reference Section’s title)
paginatedDisplay all endpoints on separate pages (by default, endpoints are displayed on one single, long page)

More on customizing your API Reference here.

Include more than one API Reference

To include multiple, distinct API definitions in your documentation, you can indicate which to include using the api-name property. The api-name corresponds to the name of the folder where your API definition is housed.

For example, your file structure might look like this:

$fern/
> ├─ fern.config.json
> ├─ docs.yml
> ├─ plant-api/
> │ └─ api.yml # API definition
> └─ garden-api/
> └─ api.yml # API definition

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

docs.yml
1navigation:
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
1tabs:
2 plant-api:
3 display-name: Plant Store API
4 icon: leaf
5 garden-api:
6 display-name: Garden API
7 icon: tree
8navigation:
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