diff --git a/.vale/styles/FernStyles/Headings.yml b/.vale/styles/FernStyles/Headings.yml index 4f19e76e1..34aa15975 100644 --- a/.vale/styles/FernStyles/Headings.yml +++ b/.vale/styles/FernStyles/Headings.yml @@ -40,6 +40,7 @@ exceptions: - WebSocket - WebSocket Playground - OpenRPC + - GraphQL - gRPC - RPC - SDK diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 72f3d7d2e..18ca4b4a8 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -278,6 +278,9 @@ navigation: - page: Generate OpenRPC reference path: ./pages/api-references/generate-openrpc-ref.mdx slug: generate-openrpc-ref + - page: Generate GraphQL reference + path: ./pages/api-references/generate-graphql-ref.mdx + slug: generate-graphql-ref - section: SEO & GEO slug: seo collapsed: true diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx new file mode 100644 index 000000000..9b7d16534 --- /dev/null +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -0,0 +1,74 @@ +--- +title: Generate GraphQL reference +description: Learn how to generate and customize GraphQL API Reference documentation +--- + +Fern generates API Reference documentation from a [GraphQL schema](https://graphql.org/learn/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: + + + ```yaml + api: + specs: + - graphql: plants.schema.graphql + resource: Plants + origin: https://api.example.com/plants/graphql + - graphql: storefront.schema.graphql + resource: Storefront + origin: https://api.example.com/storefront/graphql + ``` + + +3. Reference the API in your `docs.yml` navigation: + +```yaml docs.yml +navigation: + - api: API Reference +``` + +### Configuration properties + + + Path to your GraphQL schema file. You can include multiple GraphQL specs if your project exposes more than one GraphQL API. + + + + Name of the folder that operations from this spec appear under in the API Reference sidebar. Use this to group related GraphQL operations together. + + + + URL of your GraphQL API endpoint. Fern performs [introspection](https://graphql.org/learn/introspection/) against this endpoint to fetch the schema. When set, [running `fern api update`](/learn/cli-api-reference/cli-reference/commands#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: + +```yaml title="docs.yml" +navigation: + - api: Plant GraphQL API + api-name: plant-graphql + - api: Garden GraphQL API + api-name: garden-graphql +``` + +Organize each schema in a separate directory within your Fern project: + + + + + + + + + + + + + + + diff --git a/fern/products/docs/pages/changelog/2026-02-09.mdx b/fern/products/docs/pages/changelog/2026-02-09.mdx new file mode 100644 index 000000000..4efd8e7a7 --- /dev/null +++ b/fern/products/docs/pages/changelog/2026-02-09.mdx @@ -0,0 +1,15 @@ +--- +tags: ["api-references", "configuration", "generators.yml"] +--- + +## GraphQL API Reference + +Generate API Reference documentation from a GraphQL schema. Add your `.graphql` schema file to `generators.yml` and Fern renders queries, mutations, subscriptions, and types as an interactive reference. + +```yaml generators.yml +api: + specs: + - graphql: schema.graphql +``` + +Learn more about [generating a GraphQL reference](/learn/docs/api-references/generate-graphql-ref).