Skip to navigation
API ReferencesGeneration

Generate REST API Reference

View as Markdown

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

Fern also supports gRPC, WebSocket, OpenRPC, and Webhook references.

Configuration

1

Set up your project structure

Add your specification file to your /fern directory and create a generators.yml that references it in the api.specs section:

generators.yml
api:
  specs:
    - openapi: "./openapi.yml"
2

Add the API Reference to your navigation

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

docs.yml
navigation:
  - 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.

3

Customize the layout

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

Reference a spec directly from docs.yml

Instead of creating a generators.yml, add a specs list to the api navigation item. Fern builds the API Reference from the listed files and ignores generators.yml. Paths are relative to the configuration file that contains them (docs.yml, or a version or product configuration file).

docs.yml
navigation:
  - api: API Reference
    specs:
      - type: openapi
        path: ./openapi.yml
        overrides:
          - ./openapi-overrides.yml

Each entry takes a type (openapi, asyncapi, or graphql) and a path. Optional fields: overrides (a list of Fern override files), overlays (an OpenAPI Overlay file), and namespace. To reference multiple specs, list one specs entry per file or add a separate api item per API.

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. For example:

fern
fern.config.json
docs.yml
plant-api
openapi.yml# OpenAPI spec
generators.yml# References the OpenAPI spec
garden-api
openapi.yml# OpenAPI spec
generators.yml# References the OpenAPI spec

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

docs.yml
navigation:
  - api: Plant Store
    api-name: plant-api   # Matches folder name containing your API definition
  - api: Garden
    api-name: garden-api  # Matches folder name containing your API definition