Generate REST API Reference | Fern Documentation

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

Set up your project structure

Add your specification file to your /fern directory.

Add the API Reference to your navigation

Add an api item to your navigation in docs.yml and list your spec under specs:

docs.yml

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

Or reference the spec in the api.specs section of generators.yml and add - api: API Reference without specs:

generators.yml

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

Fern populates your endpoints, types, code snippets, and request and response examples from your API definition. To show realistic data, add examples to your spec with OpenAPI example fields or x-fern-examples.

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

A specs list on the api navigation item tells Fern which files to build the API Reference from. When specs is set, Fern ignores generators.yml for that API Reference. 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

Flat layout

Tabbed layout

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