API References

Generate REST API Reference

View as Markdown

Fern generates REST API Reference documentation from an OpenAPI specification or Fern Definition. Once the API definition is set up, adding it to the docs takes just one line of configuration.

Fern also supports GraphQL, WebSocket (AsyncAPI or Fern Definition), OpenRPC, and Webhook references.

Configuration

1

Set up your project structure

For OpenAPI/AsyncAPI: Add your specification file to your /fern directory 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)

generators.yml
1api:

2  specs:

3    - openapi: "./openapi.yml"
2

Add the API Reference to your navigation

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

docs.yml
1navigation:

2  - api: API Reference

Fern will automatically populate your endpoints, types, and code snippets from your API definition. Request and response examples are generated using AI to show realistic data instead of placeholder values.

For a full list of configuration options and layout customizations, see Customize API Reference layout.

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
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