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 the live example site or browse the source on GitHub.

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

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.