API References

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.

How to add a GraphQL endpoint

  1. Add your GraphQL schema files to your /fern directory.
  2. Configure your generators.yml to point to your GraphQL schemas:
generators.yml
1api:
2  specs:
3    - graphql: plants.schema.graphql
4      name: Plants
5      origin: https://api.example.com/plants/graphql
6    - graphql: storefront.schema.graphql
7      name: Storefront
8      origin: https://api.example.com/storefront/graphql
  1. Reference the API in your docs.yml navigation:
docs.yml
1navigation:
2  - api: API Reference

Configuration properties

api.specs[].graphql
Required

Path to your GraphQL schema file. You can include multiple GraphQL specs if your project exposes more than one GraphQL API.

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.

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.

Include more than one GraphQL reference

To include multiple GraphQL definitions in your documentation, use the api-name property:

docs.yml
1navigation:
2  - api: Plant GraphQL API
3    api-name: plant-graphql
4  - api: Garden GraphQL API
5    api-name: garden-graphql

Organize each schema in a separate directory within your Fern project:

fern
apis
plant-graphql# Plant GraphQL schema
schema.graphql
generators.yml
garden-graphql# Garden GraphQL schema
schema.graphql
generators.yml

Customize the layout

Use the layout property in docs.yml to control how GraphQL operations appear in the sidebar. Reference individual operations with the operation keyword using the format OPERATION_TYPE operationName, where OPERATION_TYPE is QUERY, MUTATION, or SUBSCRIPTION.

You can also set a custom title, slug, hidden, or availability on each operation:

docs.yml
1navigation:
2  - api: GraphQL API Reference
3    layout:
4      - operation: QUERY getPlant
5        title: Get plant details
6        slug: get-plant
7      - operation: MUTATION createPlant
8        title: Create a plant
9      - operation: MUTATION deletePlant
10        hidden: true
11      - operation: SUBSCRIPTION plantUpdates
12        availability: beta

Group operations into sections

Organize operations under custom sections:

docs.yml
1navigation:
2  - api: GraphQL API Reference
3    layout:
4      - section: Plants
5        contents:
6          - operation: QUERY getPlant
7          - operation: MUTATION createPlant
8      - section: Real-time
9        contents:
10          - operation: SUBSCRIPTION plantUpdates

Namespaced operations

If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate:

docs.yml
1navigation:
2  - api: GraphQL API Reference
3    layout:
4      - operation: QUERY admin.getPlant
5      - operation: QUERY public.getPlant

For the full set of layout options that apply to all API types (alphabetizing, flattening, adding pages and links, and more), see Customize API Reference layout.