API ReferencesGeneration

Generate GraphQL Reference

View as Markdown

Fern generates API Reference documentation from a GraphQL schema. Add your schema file to your Fern project and Fern renders queries, mutations, subscriptions, and types as an interactive reference.

See live example

Configuration

1

Set up your project structure

Add your GraphQL schema file to your /fern directory and create a generators.yml that references it:

generators.yml
1api:
2  specs:
3    - graphql: plants.schema.graphql
4      name: Plants
5      origin: https://api.example.com/plants/graphql
2

Add the GraphQL Reference to your navigation

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

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

Customize the layout

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

Include more than one GraphQL Reference

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

fern
fern.config.json
docs.yml
plant-graphql
schema.graphql# Plant GraphQL schema
generators.yml
garden-graphql
schema.graphql# Garden GraphQL schema
generators.yml
docs.yml
1navigation:
2  - api: Plant GraphQL API
3    api-name: plant-graphql
4  - api: Garden GraphQL API
5    api-name: garden-graphql

Compile a schema split across multiple files

A schema split across several SDL files, the typical shape for Apollo Federation subgraphs, compiles into a single schema. List each file as its own spec and give the specs the same name:

generators.yml
1api:
2  specs:
3    - graphql: plants.graphql
4      name: Plants
5    - graphql: gardens.graphql
6      name: Plants

Specs that share a name, or that omit name, are parsed together, so a file can reference types defined in a sibling file and each file can extend type Query or extend type Mutation. Specs with different name values, and specs in different API workspaces, remain independent.

The reference shows the client-facing schema: federation directives are stripped and @inaccessible types and members are omitted. If two files declare the same member differently, the first declaration wins and Fern logs a warning.

Specs sharing a namespace previously resolved collisions last-wins, without a warning. To keep the previous output, reorder the specs or give them distinct name values.

Configuration properties

api.specs[].graphql
Required

Path to your GraphQL schema file. Include multiple GraphQL specs if your project exposes more than one GraphQL API, or if one schema is split across files.

api.specs[].name

Name of the folder that operations from this spec appear under in the API Reference sidebar. Use this to group related GraphQL operations together. Specs that share a name are compiled into one schema.

api.specs[].origin

URL of your GraphQL API endpoint. Fern performs introspection against this endpoint to fetch the schema. When set, running fern api update updates the local schema from this endpoint.

Types

Fern generates a page for every named type in your schema, under a Types section at the root of the API Reference. Pages are grouped by kind: Objects, Inputs, Enums, Scalars, Interfaces, and Unions. Kinds your schema doesn’t declare produce no group, and all GraphQL schemas in the API section share one Types section.

Type pages live at <api-reference>/types/<kind>/<type-name>, such as /api-reference/types/objects/plant. Interface pages also list the types that implement the interface. Types that only group operations, such as a Mutation.plants: PlantMutations namespace type, don’t get a page.