From fef5061b71ceac129cc45c4511475be5a20f6460 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Tue, 17 Feb 2026 16:47:31 +0000 Subject: [PATCH 1/8] Make Generate [x] Reference pages consistent with Steps pattern and link to Customize page --- .../api-references/customize-api-ref.mdx | 2 +- .../pages/api-references/generate-api-ref.mdx | 2 +- .../api-references/generate-graphql-ref.mdx | 106 ++++--------- .../api-references/generate-openrpc-ref.mdx | 37 +++-- .../api-references/generate-webhook-ref.mdx | 139 ++++++------------ .../api-references/generate-websocket-ref.mdx | 57 ++++--- 6 files changed, 126 insertions(+), 217 deletions(-) diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index 0b6171e27..5fd2911fd 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -96,7 +96,7 @@ The `layout` option allows you to specify the order of sub-packages, sections, e ``` - You can reference an operation using the format `operation: OPERATION_TYPE operationName`. See [GraphQL layout customization](/learn/docs/api-references/generate-graphql-ref#customize-the-layout) for more details. + You can reference an operation using the format `operation: OPERATION_TYPE operationName`. See [GraphQL-specific layout options](/learn/docs/api-references/generate-graphql-ref#graphql-specific-layout-options) for more details. ```yaml title="docs.yml" navigation: - api: API Reference diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx index f3fcc4ee4..65037ce2a 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -6,7 +6,7 @@ description: Use Fern Docs to generate REST API Reference documentation from an Fern generates REST API Reference documentation from an [OpenAPI specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview). Once the API definition is set up, adding it to the docs takes just one line of configuration. - Fern also supports [GraphQL](/learn/docs/api-references/generate-graphql-ref), [WebSocket](/learn/docs/api-references/generate-websocket-ref) (AsyncAPI or Fern Definition), [OpenRPC](/learn/docs/api-references/generate-openrpc-ref), and [Webhook](/learn/docs/api-references/generate-webhook-reference) references. + Fern also supports [GraphQL](/learn/docs/api-references/generate-graphql-ref), [WebSocket](/learn/docs/api-references/generate-websocket-ref) (AsyncAPI or Fern Definition), [OpenRPC](/learn/docs/api-references/generate-openrpc-ref), and [Webhook](/learn/docs/api-references/generate-webhook-ref) references. ## Configuration diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index 79d72c077..bb38ed00e 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -1,35 +1,40 @@ --- -title: Generate GraphQL reference -description: Learn how to generate and customize GraphQL API Reference documentation +title: Generate GraphQL Reference +description: Use Fern Docs to generate GraphQL API Reference documentation from a GraphQL schema. --- 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 +## Configuration -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 - name: Plants - origin: https://api.example.com/plants/graphql - - graphql: storefront.schema.graphql - name: Storefront - origin: https://api.example.com/storefront/graphql - ``` - +Add your GraphQL schema file to your `/fern` directory and create a `generators.yml` that references it: -3. Reference the API in your `docs.yml` navigation: +```yaml generators.yml +api: + specs: + - graphql: plants.schema.graphql + name: Plants + origin: https://api.example.com/plants/graphql +``` + + + -```yaml docs.yml +Add `- api: API Reference` to your navigation in `docs.yml`: + +```yml docs.yml navigation: - api: API Reference ``` + + + +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + ### Configuration properties @@ -44,9 +49,9 @@ navigation: 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 +### Include more than one GraphQL Reference -To include multiple GraphQL definitions in your documentation, use the `api-name` property: +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. ```yaml title="docs.yml" navigation: @@ -56,28 +61,9 @@ navigation: api-name: garden-graphql ``` -Organize each schema in a separate directory within your Fern project: - - - - - - - - - - - - - - - - -## Customize the layout +### GraphQL-specific layout options -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: +Reference individual operations in the `layout` using the `operation` keyword with the format `OPERATION_TYPE operationName`, where `OPERATION_TYPE` is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate (e.g., `QUERY admin.getPlant`). ```yaml title="docs.yml" navigation: @@ -87,42 +73,6 @@ navigation: title: Get plant details slug: get-plant - operation: MUTATION createPlant - title: Create a plant - - operation: MUTATION deletePlant - hidden: true - operation: SUBSCRIPTION plantUpdates availability: beta ``` - -### Group operations into sections - -Organize operations under custom sections: - -```yaml title="docs.yml" -navigation: - - api: GraphQL API Reference - layout: - - section: Plants - contents: - - operation: QUERY getPlant - - operation: MUTATION createPlant - - section: Real-time - contents: - - operation: SUBSCRIPTION plantUpdates -``` - -### Namespaced operations - -If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate: - -```yaml title="docs.yml" -navigation: - - api: GraphQL API Reference - layout: - - operation: QUERY admin.getPlant - - 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](/learn/docs/api-references/customize-api-reference-layout). - diff --git a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx index 903b451c3..81cd9524e 100644 --- a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx @@ -9,21 +9,36 @@ Fern generates OpenRPC Reference documentation from an [OpenRPC](https://open-rp Alchemy's OpenRPC API Reference Example -## How to add an OpenRPC endpoint +## Configuration -1. Add your OpenRPC specification file (e.g., `openrpc.yaml`) to your `/fern` directory. -2. Configure your `generators.yml` to point to your OpenRPC spec: + + - - ```yaml - api: - specs: - - openrpc: ../../api-specs/openrpc/wallet.yml - ``` - +Add your OpenRPC specification file (e.g., `openrpc.yaml`) to your `/fern` directory and create a `generators.yml` that references it: + +```yaml generators.yml +api: + specs: + - openrpc: ./openrpc.yml +``` + + + + +Add `- api: API Reference` to your navigation in `docs.yml`: + +```yml docs.yml +navigation: + - api: API Reference +``` + + + + +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). ### Configuration properties Path to your OpenRPC specification file. You can include multiple OpenRPC specs if your project exposes more than one JSON-RPC API. - \ No newline at end of file + diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index 59a6f19ec..4a6dedd20 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx @@ -3,84 +3,50 @@ title: Generate Webhook Reference description: Use Fern Docs to generate your Webhook Reference documentation from an OpenAPI spec or Fern Definition. --- -Fern generates Webhook Reference documentation from an [OpenAPI specification](../../openapi-definition/endpoints/webhooks) or [Fern Definition](../../fern-definition/webhooks). +Fern generates Webhook Reference documentation from an [OpenAPI specification](/learn/api-definitions/openapi/endpoints/webhooks) or [Fern Definition](/learn/api-definitions/ferndef/webhooks). Fern supports webhooks through: - **OpenAPI 3.1+**: Use the native `webhooks` field with an `operationId` (recommended) - **OpenAPI 3.0**: Use the `x-fern-webhook: true` extension - **Fern Definition**: Define `webhooks` in your specification -## Configure your webhook reference +## Configuration -Add a page title (`api`) and reference the name of the directory where your where your webhook definition is located (`api-name`). + + -```yml docs.yml {11-12} +For **OpenAPI**: Add your specification file to your `/fern` directory and create a `generators.yml` that references it: + +```yaml generators.yml +api: + path: openapi/openapi.yml +``` + +For **Fern Definition**: Add a `definition/` directory with your webhook definition files (Fern auto-detects this). + + + + +Add `- api: Webhook Reference` to your navigation in `docs.yml`: + +```yml docs.yml navigation: - - section: Introduction - contents: - - page: Getting Started - path: ../introduction/getting-started.md - - page: Authentication - path: ../introduction/authentication.md - - api: API Reference - api-name: api-v1 - display-errors: true - api: Webhook Reference api-name: webhooks-v1 ``` -For a real-world example of webhook documentation generated from an API definition, check out [Webflow's webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission). +Use the `api-name` property to reference the folder containing your webhook definition. -### Directory structure -Your webhooks should be defined in a dedicated folder within your Fern project: + + - - - - - - - - - - - - - - - - -If you're using OpenAPI, your `generators.yml` file should point to your OpenAPI specification: - -```yml generators.yml -api: - path: openapi/openapi.yml -``` +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). -You can read more about how to define webhooks in your OpenAPI specification [here](/learn/api-definitions/openapi/endpoints/webhooks). - - - - - - - - - - - - - - - - - -You can read more about how to define webhooks in your Fern Definition [here](/learn/api-definition/fern/webhooks). - - +For a real-world example of webhook documentation generated from an API definition, check out [Webflow's webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission). -### Include more than one webhook reference -To include multiple webhook definitions in your documentation, use the `api-name` property: +### Include more than one Webhook Reference + +To include multiple webhook definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your webhook definition. ```yaml title="docs.yml" navigation: @@ -90,55 +56,36 @@ navigation: api-name: order-webhooks ``` -When using multiple webhook definitions, organize them in separate directories within your Fern project: - - - - - - - - - - - - - - - - - - - - -### Create individual documentation pages for each webhook event - -To display each webhook event as an individual page with rich examples: +### Reference individual webhook events + +To display each webhook event as an individual page, reference it in the `layout` using the `subpackage_{tag}.{webhook-event-name}` format: -Reference individual webhook pages using the `subpackage_{tag}.{webhook-event-name}` format, where: -- `{tag}` is the first tag (lowercase) from your webhook definition -- `{webhook-event-name}` is the `operationId` from your webhook definition - ```yaml title="docs.yml" navigation: - - subpackage_plants.newPlantWebhook + - api: Webhook Reference + api-name: webhooks-v1 + layout: + - subpackage_plants.newPlantWebhook ``` +Where `{tag}` is the first tag (lowercase) and `{webhook-event-name}` is the `operationId` from your webhook definition. + - For OpenAPI, you must have the `tags` and `example` properties defined [in your webhook specification](/api-definitions/openapi/endpoints/webhooks). + For OpenAPI, you must have the `tags` and `example` properties defined [in your webhook specification](/learn/api-definitions/openapi/endpoints/webhooks). -Reference the individual webhook event using the `subpackage_{name}.{webhook-event-name}` format, where: -- `{name}` is the name of your API as defined in the `api.yml` file for your webhook definition. -- `{webhook-event-name}` is the identifier from your webhook definition - ```yaml title="docs.yml" navigation: - - subpackage_api.newPlantWebhook + - api: Webhook Reference + api-name: webhooks-v1 + layout: + - subpackage_api.newPlantWebhook ``` + +Where `{name}` is the name of your API as defined in `api.yml` and `{webhook-event-name}` is the identifier from your webhook definition. diff --git a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx index 2283c4732..7ec269c17 100644 --- a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx @@ -13,33 +13,30 @@ Fern generates WebSocket Reference documentation from an [AsyncAPI specification ## Configuration -1. For both Fern Definition and AsyncAPI, add your WebSocket specification file to your `/fern` directory. - -2. For AsyncAPI only, reference the file in `generators.yml`: - - - ```yaml - api: - path: asyncapi.yml # Location of spec (required) - origin: https://github.com/your-org/your-repo/blob/main/asyncapi.yml # Fetch from remote URL (optional) - ``` - - - Fern Definition WebSocket files are auto-discovered (no additional configuration required). - -### Customize layout - -You can customize the WebSocket endpoint display with `title` and `slug` properties, similar to REST endpoints. For more details, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - - ```yaml title="docs.yml" {9-10} - navigation: - - api: API Reference - layout: - - user: - - endpoint: user.create - title: Create a User - slug: user-creation - - user.delete - - endpoint: WSS /v1/realtime - title: Realtime - ``` + + + +For **AsyncAPI**: Add your specification file to your `/fern` directory and create a `generators.yml` that references it: + +```yaml generators.yml +api: + path: asyncapi.yml + origin: https://github.com/your-org/your-repo/blob/main/asyncapi.yml # optional +``` + +For **Fern Definition**: Add your WebSocket definition files to a `definition/` directory (Fern auto-detects this). + + + + +Add `- api: API Reference` to your navigation in `docs.yml`: + +```yml docs.yml +navigation: + - api: API Reference +``` + + + + +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). From 44873679e8382a3a02169f458f441bcdafd8e8fb Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 18 Feb 2026 17:54:09 +0000 Subject: [PATCH 2/8] Add file structure diagrams for multi-API setup to all Generate pages --- .../api-references/generate-graphql-ref.mdx | 12 ++++++++++ .../api-references/generate-openrpc-ref.mdx | 24 +++++++++++++++++++ .../api-references/generate-webhook-ref.mdx | 14 +++++++++++ .../api-references/generate-websocket-ref.mdx | 24 +++++++++++++++++++ 4 files changed, 74 insertions(+) diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index bb38ed00e..e6bc355ec 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -53,6 +53,18 @@ For a full list of configuration options and layout customizations, see [Customi 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. +```bash +fern/ + ├─ fern.config.json + ├─ docs.yml + ├─ plant-graphql/ + │ ├─ schema.graphql # Plant GraphQL schema + │ └─ generators.yml + └─ garden-graphql/ + ├─ schema.graphql # Garden GraphQL schema + └─ generators.yml +``` + ```yaml title="docs.yml" navigation: - api: Plant GraphQL API diff --git a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx index 81cd9524e..fbebea0c2 100644 --- a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx @@ -37,6 +37,30 @@ navigation: For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). +### Include more than one OpenRPC Reference + +To include multiple OpenRPC definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your OpenRPC definition. + +```bash +fern/ + ├─ fern.config.json + ├─ docs.yml + ├─ wallet-api/ + │ ├─ openrpc.yml # Wallet OpenRPC spec + │ └─ generators.yml + └─ nft-api/ + ├─ openrpc.yml # NFT OpenRPC spec + └─ generators.yml +``` + +```yaml title="docs.yml" +navigation: + - api: Wallet API + api-name: wallet-api + - api: NFT API + api-name: nft-api +``` + ### Configuration properties diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index 4a6dedd20..a72d5b3e3 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx @@ -48,6 +48,20 @@ For a real-world example of webhook documentation generated from an API definiti To include multiple webhook definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your webhook definition. +```bash +fern/ + ├─ fern.config.json + ├─ docs.yml + ├─ payment-webhooks/ + │ ├─ openapi/ + │ │ └─ openapi.yml # Payment webhook OpenAPI spec + │ └─ generators.yml + └─ order-webhooks/ + ├─ openapi/ + │ └─ openapi.yml # Order webhook OpenAPI spec + └─ generators.yml +``` + ```yaml title="docs.yml" navigation: - api: Payment Webhooks diff --git a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx index 7ec269c17..3c485d88e 100644 --- a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx @@ -40,3 +40,27 @@ navigation: For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + +### Include more than one WebSocket Reference + +To include multiple WebSocket definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your WebSocket definition. + +```bash +fern/ + ├─ fern.config.json + ├─ docs.yml + ├─ streaming-api/ + │ ├─ asyncapi.yml # Streaming WebSocket AsyncAPI spec + │ └─ generators.yml + └─ realtime-api/ + ├─ asyncapi.yml # Realtime WebSocket AsyncAPI spec + └─ generators.yml +``` + +```yaml title="docs.yml" +navigation: + - api: Streaming API + api-name: streaming-api + - api: Realtime API + api-name: realtime-api +``` From a7d2ed8834aadc50ff5b5008a362b5cd6d8dec52 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Wed, 18 Feb 2026 17:57:43 +0000 Subject: [PATCH 3/8] Move GraphQL-specific layout options to Customize API Reference layout page --- .../pages/api-references/customize-api-ref.mdx | 6 +++++- .../api-references/generate-graphql-ref.mdx | 16 ---------------- 2 files changed, 5 insertions(+), 17 deletions(-) diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index 5fd2911fd..462443263 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -96,13 +96,17 @@ The `layout` option allows you to specify the order of sub-packages, sections, e ``` - You can reference an operation using the format `operation: OPERATION_TYPE operationName`. See [GraphQL-specific layout options](/learn/docs/api-references/generate-graphql-ref#graphql-specific-layout-options) for more details. + Reference individual GraphQL operations using the `operation` keyword with the format `OPERATION_TYPE operationName`, where `OPERATION_TYPE` is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. You can also set a custom `title`, `slug`, or `availability` on each operation. + + If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate (e.g., `QUERY admin.getPlant`). ```yaml title="docs.yml" navigation: - api: API Reference layout: - user: - operation: QUERY getUser + title: Get user details + slug: get-user - operation: MUTATION createUser - operation: MUTATION deleteUser ``` diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index e6bc355ec..ae93e56a0 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -72,19 +72,3 @@ navigation: - api: Garden GraphQL API api-name: garden-graphql ``` - -### GraphQL-specific layout options - -Reference individual operations in the `layout` using the `operation` keyword with the format `OPERATION_TYPE operationName`, where `OPERATION_TYPE` is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate (e.g., `QUERY admin.getPlant`). - -```yaml title="docs.yml" -navigation: - - api: GraphQL API Reference - layout: - - operation: QUERY getPlant - title: Get plant details - slug: get-plant - - operation: MUTATION createPlant - - operation: SUBSCRIPTION plantUpdates - availability: beta -``` From 42300a232ce5864db90123a54bafea83db678e26 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 18 Feb 2026 14:05:30 -0500 Subject: [PATCH 4/8] move more to customize page --- fern/products/docs/docs.yml | 63 +++++++++++-------- .../api-references/customize-api-ref.mdx | 27 ++++---- .../pages/api-references/generate-api-ref.mdx | 30 +++++---- .../api-references/generate-graphql-ref.mdx | 29 +++++---- .../api-references/generate-openrpc-ref.mdx | 29 +++++---- .../api-references/generate-webhook-ref.mdx | 35 ++++++----- .../api-references/generate-websocket-ref.mdx | 29 +++++---- 7 files changed, 138 insertions(+), 104 deletions(-) diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index bf5f1f302..1978deb4b 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -247,33 +247,42 @@ navigation: - section: API References collapsed: true contents: - - page: Generate REST API Reference - path: ./pages/api-references/generate-api-ref.mdx - slug: generate-api-ref - - page: SDK snippets - path: ./pages/api-references/sdk-snippets.mdx - - page: HTTP snippets - path: ./pages/api-references/http-snippets.mdx - - page: API Explorer - path: ./pages/api-references/api-explorer.mdx - slug: api-explorer - - page: Audiences - path: ./pages/api-references/audiences.mdx - - page: Customize API Reference layout - path: ./pages/api-references/customize-api-ref.mdx - - page: Write Markdown in API Reference - path: ./pages/api-references/api-ref-content.mdx - - page: Generate Webhook Reference - path: ./pages/api-references/generate-webhook-ref.mdx - - page: Generate WebSocket Reference - path: ./pages/api-references/generate-websocket-ref.mdx - slug: generate-websocket-ref - - 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: Generation + skip-slug: true + contents: + - page: REST API Reference + path: ./pages/api-references/generate-api-ref.mdx + slug: generate-api-ref + - page: Webhook Reference + path: ./pages/api-references/generate-webhook-ref.mdx + - page: WebSocket Reference + path: ./pages/api-references/generate-websocket-ref.mdx + slug: generate-websocket-ref + - page: OpenRPC Reference + path: ./pages/api-references/generate-openrpc-ref.mdx + slug: generate-openrpc-ref + - page: GraphQL Reference + path: ./pages/api-references/generate-graphql-ref.mdx + slug: generate-graphql-ref + - section: Customization + skip-slug: true + contents: + - page: Customize API Reference layout + path: ./pages/api-references/customize-api-ref.mdx + - page: Audiences + path: ./pages/api-references/audiences.mdx + - page: Write Markdown in API Reference + path: ./pages/api-references/api-ref-content.mdx + - section: Code exploration + skip-slug: true + contents: + - page: SDK snippets + path: ./pages/api-references/sdk-snippets.mdx + - page: HTTP snippets + path: ./pages/api-references/http-snippets.mdx + - page: API Explorer + path: ./pages/api-references/api-explorer.mdx + slug: api-explorer - section: SEO & GEO slug: seo collapsed: true diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index 462443263..8d15cd86f 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -96,7 +96,7 @@ The `layout` option allows you to specify the order of sub-packages, sections, e ``` - Reference individual GraphQL operations using the `operation` keyword with the format `OPERATION_TYPE operationName`, where `OPERATION_TYPE` is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. You can also set a custom `title`, `slug`, or `availability` on each operation. + Reference individual GraphQL operations using the `operation` keyword with the format `OPERATION_TYPE operationName`, where `OPERATION_TYPE` is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate (e.g., `QUERY admin.getPlant`). ```yaml title="docs.yml" @@ -105,24 +105,10 @@ The `layout` option allows you to specify the order of sub-packages, sections, e layout: - user: - operation: QUERY getUser - title: Get user details - slug: get-user - operation: MUTATION createUser - operation: MUTATION deleteUser ``` - - You can reference a WebSocket endpoint using the format `WSS /path/name`. - ```yaml title="docs.yml" - navigation: - - api: API Reference - layout: - - plants: - - GET /plants - - WSS /plants/live-updates - - WSS /plants/growth-monitor - ``` - @@ -209,6 +195,17 @@ To customize the display of an endpoint, you can add a `title`. You can also use slug: live-updates ``` + + ```yaml title="docs.yml" {6-8} + navigation: + - api: API Reference + layout: + - user: + - operation: QUERY getUser + title: Get user details + slug: get-user + ``` + diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx index 65037ce2a..255467e34 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -39,7 +39,9 @@ Fern will automatically populate your endpoints, types, and code snippets from y -For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + + For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + ### Include more than one API Reference @@ -47,17 +49,21 @@ To include multiple, distinct API definitions in your documentation, use the `ap This works with any combination of OpenAPI and Fern Definition formats. For example: -```bash -fern/ - ├─ fern.config.json - ├─ docs.yml - ├─ plant-api/ - │ ├─ openapi.yml # OpenAPI spec - │ └─ generators.yml # References the OpenAPI spec - └─ garden-api/ - └─ definition/ # Fern Definition (auto-detected) - └─ api.yml -``` + + + + + + + + + + + + + + + For a simple setup without tabs, you can include multiple API References directly in your navigation: diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index ae93e56a0..19e112adc 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -33,7 +33,9 @@ navigation: -For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + + For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + ### Configuration properties @@ -53,17 +55,20 @@ For a full list of configuration options and layout customizations, see [Customi 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. -```bash -fern/ - ├─ fern.config.json - ├─ docs.yml - ├─ plant-graphql/ - │ ├─ schema.graphql # Plant GraphQL schema - │ └─ generators.yml - └─ garden-graphql/ - ├─ schema.graphql # Garden GraphQL schema - └─ generators.yml -``` + + + + + + + + + + + + + + ```yaml title="docs.yml" navigation: diff --git a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx index fbebea0c2..cc318bab1 100644 --- a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx @@ -35,23 +35,28 @@ navigation: -For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + + For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + ### Include more than one OpenRPC Reference To include multiple OpenRPC definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your OpenRPC definition. -```bash -fern/ - ├─ fern.config.json - ├─ docs.yml - ├─ wallet-api/ - │ ├─ openrpc.yml # Wallet OpenRPC spec - │ └─ generators.yml - └─ nft-api/ - ├─ openrpc.yml # NFT OpenRPC spec - └─ generators.yml -``` + + + + + + + + + + + + + + ```yaml title="docs.yml" navigation: diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index a72d5b3e3..96d7be235 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx @@ -40,7 +40,9 @@ Use the `api-name` property to reference the folder containing your webhook defi -For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + + For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + For a real-world example of webhook documentation generated from an API definition, check out [Webflow's webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission). @@ -48,19 +50,24 @@ For a real-world example of webhook documentation generated from an API definiti To include multiple webhook definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your webhook definition. -```bash -fern/ - ├─ fern.config.json - ├─ docs.yml - ├─ payment-webhooks/ - │ ├─ openapi/ - │ │ └─ openapi.yml # Payment webhook OpenAPI spec - │ └─ generators.yml - └─ order-webhooks/ - ├─ openapi/ - │ └─ openapi.yml # Order webhook OpenAPI spec - └─ generators.yml -``` + + + + + + + + + + + + + + + + + + ```yaml title="docs.yml" navigation: diff --git a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx index 3c485d88e..04158f1cf 100644 --- a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx @@ -39,23 +39,28 @@ navigation: -For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + + For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + ### Include more than one WebSocket Reference To include multiple WebSocket definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your WebSocket definition. -```bash -fern/ - ├─ fern.config.json - ├─ docs.yml - ├─ streaming-api/ - │ ├─ asyncapi.yml # Streaming WebSocket AsyncAPI spec - │ └─ generators.yml - └─ realtime-api/ - ├─ asyncapi.yml # Realtime WebSocket AsyncAPI spec - └─ generators.yml -``` + + + + + + + + + + + + + + ```yaml title="docs.yml" navigation: From a35b77c3602b33f212ada81e327ba4ad2989820d Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 18 Feb 2026 14:20:27 -0500 Subject: [PATCH 5/8] graphql improvements --- .../api-references/customize-api-ref.mdx | 47 ++++++++++++++++--- .../pages/api-references/generate-api-ref.mdx | 9 ++-- .../api-references/generate-graphql-ref.mdx | 9 ++-- .../api-references/generate-openrpc-ref.mdx | 9 ++-- .../api-references/generate-webhook-ref.mdx | 9 ++-- .../api-references/generate-websocket-ref.mdx | 9 ++-- 6 files changed, 65 insertions(+), 27 deletions(-) diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index 8d15cd86f..c24b3b00b 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -96,9 +96,7 @@ The `layout` option allows you to specify the order of sub-packages, sections, e ``` - Reference individual GraphQL operations using the `operation` keyword with the format `OPERATION_TYPE operationName`, where `OPERATION_TYPE` is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. - - If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate (e.g., `QUERY admin.getPlant`). + Reference individual GraphQL operations using the `operation` keyword with the format `OPERATION_TYPE operationName`, where `OPERATION_TYPE` is `QUERY`, `MUTATION`, or `SUBSCRIPTION`. If your schema includes operations that share the same name across different namespaces, use dot notation to disambiguate. ```yaml title="docs.yml" navigation: - api: API Reference @@ -107,6 +105,8 @@ The `layout` option allows you to specify the order of sub-packages, sections, e - operation: QUERY getUser - operation: MUTATION createUser - operation: MUTATION deleteUser + - operation: QUERY admin.getPlant + - operation: QUERY public.getPlant ``` @@ -253,6 +253,15 @@ You can hide an endpoint from the API Reference by setting `hidden` to `true`. T hidden: true ``` + + ```yaml title="docs.yml" {5} + navigation: + - api: API Reference + layout: + - operation: MUTATION deletePlant + hidden: true + ``` + ### Adding custom sections @@ -275,16 +284,30 @@ You can add arbitrary folders in the sidebar by adding a `section` to your API R ```yaml title="docs.yml" - navigation: + navigation: - api: API Reference - layout: + layout: - section: My Section icon: flower - contents: + contents: - user.update - plant ``` + + ```yaml title="docs.yml" + navigation: + - api: API Reference + layout: + - section: Plants + contents: + - operation: QUERY getPlant + - operation: MUTATION createPlant + - section: Real-time + contents: + - operation: SUBSCRIPTION plantUpdates + ``` + @@ -361,7 +384,17 @@ navigation: When you set availability for a section, all endpoints in that section will inherit the section-level availability unless explicitly overridden in your API definition. -You can't set availability for individual endpoints in `docs.yml`. Endpoint availability must be configured directly in your API definition. Learn more about availability for [OpenAPI](/learn/api-definitions/openapi/extensions/availability) or [Fern Definition](/learn/api-definitions/ferndef/availability). + + You can't set availability for individual endpoints in `docs.yml` — except for GraphQL, where `availability` can be set per operation. For OpenAPI and Fern Definition, endpoint availability must be configured directly in your API definition. Learn more about availability for [OpenAPI](/learn/api-definitions/openapi/extensions/availability) or [Fern Definition](/learn/api-definitions/ferndef/availability). + + ```yaml title="docs.yml" + navigation: + - api: API Reference + layout: + - operation: SUBSCRIPTION plantUpdates + availability: beta + ``` + ### Displaying endpoint errors diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx index 255467e34..0336f4f86 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -37,11 +37,12 @@ navigation: Fern will automatically populate your endpoints, types, and code snippets from your API definition. Request and response examples are [generated using AI](/learn/docs/ai-features/ai-examples) to show realistic data instead of placeholder values. - + - - For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). + + + ### Include more than one API Reference diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index 19e112adc..4d0481274 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -31,11 +31,12 @@ navigation: ``` - + + +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - - For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - + + ### Configuration properties diff --git a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx index cc318bab1..5080cf932 100644 --- a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx @@ -33,11 +33,12 @@ navigation: ``` - + + +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - - For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - + + ### Include more than one OpenRPC Reference diff --git a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx index 96d7be235..63c17be2e 100644 --- a/fern/products/docs/pages/api-references/generate-webhook-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-webhook-ref.mdx @@ -38,11 +38,12 @@ navigation: Use the `api-name` property to reference the folder containing your webhook definition. - + + +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - - For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - + + For a real-world example of webhook documentation generated from an API definition, check out [Webflow's webhooks](https://developers.webflow.com/data/reference/webhooks/events/form-submission). diff --git a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx index 04158f1cf..a24e0a1a1 100644 --- a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx @@ -37,11 +37,12 @@ navigation: ``` - + + +For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - - For a full list of configuration options and layout customizations, see [Customize API Reference layout](/learn/docs/api-references/customize-api-reference-layout). - + + ### Include more than one WebSocket Reference From 1507b8dc6e2aeaf8f1829933730a953633e8b0ad Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 18 Feb 2026 16:21:15 -0500 Subject: [PATCH 6/8] clean up availability description --- fern/products/docs/pages/api-references/customize-api-ref.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index c24b3b00b..2e833ca24 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -385,7 +385,9 @@ navigation: When you set availability for a section, all endpoints in that section will inherit the section-level availability unless explicitly overridden in your API definition. - You can't set availability for individual endpoints in `docs.yml` — except for GraphQL, where `availability` can be set per operation. For OpenAPI and Fern Definition, endpoint availability must be configured directly in your API definition. Learn more about availability for [OpenAPI](/learn/api-definitions/openapi/extensions/availability) or [Fern Definition](/learn/api-definitions/ferndef/availability). + You can't set availability for individual OpenAPI and Fern Definition endpoints in `docs.yml` — endpoint availability must be configured directly in your API definition. Learn more about availability for [OpenAPI](/learn/api-definitions/openapi/extensions/availability) or [Fern Definition](/learn/api-definitions/ferndef/availability). + + For GraphQL, `availability` can be set per operation: ```yaml title="docs.yml" navigation: From a64b35bf007d599976f357395103992f18ff6438 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 19 Feb 2026 18:01:51 -0500 Subject: [PATCH 7/8] small updates --- .../pages/api-references/generate-api-ref.mdx | 7 ++++- .../api-references/generate-graphql-ref.mdx | 28 +++++++++---------- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx index 0336f4f86..1ad0a51e0 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -66,6 +66,8 @@ This works with any combination of OpenAPI and Fern Definition formats. For exam + + For a simple setup without tabs, you can include multiple API References directly in your navigation: ```yaml title="docs.yml" @@ -75,7 +77,8 @@ navigation: - api: Garden api-name: garden-api # Matches folder name containing your API definition ``` - + + When using tabs, each API Reference must be placed within a tab's `layout`: ```yaml title="docs.yml" {12, 17} @@ -98,3 +101,5 @@ navigation: api-name: garden-api # Matches folder name containing your API definition skip-slug: true ``` + + \ No newline at end of file diff --git a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx index 4d0481274..e98754f4f 100644 --- a/fern/products/docs/pages/api-references/generate-graphql-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-graphql-ref.mdx @@ -38,20 +38,6 @@ For a full list of configuration options and layout customizations, see [Customi -### 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. The `api-name` corresponds to the folder name containing your GraphQL schema. @@ -78,3 +64,17 @@ navigation: - api: Garden GraphQL API api-name: garden-graphql ``` + +### 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. + From 62fbec15cd5950bbcbfea515caca90a5c62551ea Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 23 Feb 2026 15:15:38 -0500 Subject: [PATCH 8/8] fix example --- .../api-references/customize-api-ref.mdx | 76 +++++++++++++------ 1 file changed, 53 insertions(+), 23 deletions(-) diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index 2e833ca24..7adff7a44 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -102,12 +102,9 @@ The `layout` option allows you to specify the order of sub-packages, sections, e - api: API Reference layout: - user: - - operation: QUERY getUser - - operation: MUTATION createUser - - operation: MUTATION deleteUser - - operation: QUERY admin.getPlant - - operation: QUERY public.getPlant - ``` + - operation: QUERY admin.getUser + - operation: MUTATION createPlant + - operation: SUBSCRIPTION plantUpdates @@ -122,24 +119,57 @@ The `layout` option allows you to specify the order of sub-packages, sections, e By default, section display names come from [service file names](/api-definitions/ferndef/endpoints/overview#service-definition) (Fern Definition) or tag names (OpenAPI) in your spec. -To override the display name of a section, use the `section` property in your `docs.yml` and reference the `lowerCamelCase` version of the original service file name (Fern Definition) or tag name (OpenAPI) in `referenced-packages`. +To override the display name of a section, use the `section` property in your `docs.yml`. -```yaml title="docs.yml" {4-6} -navigation: - - api: API Reference - layout: - - section: "Billing" # New section display name - referenced-packages: - - billing # lowerCamelCase version of original tag/service file name from your spec - contents: [] - - section: "Bank Accounts" - referenced-packages: - - bankAccounts - contents: [] -``` - - For OpenAPI, you can alternatively customize tag display names directly in your spec (or `overrides.yml` file) using the [`x-displayName` extension](/api-definitions/openapi/extensions/tag-display-names). - + + + ```yaml title="docs.yml" {4-6} + navigation: + - api: API Reference + layout: + - section: "Billing" # New section display name + referenced-packages: + - billing # lowerCamelCase version of original tag name from your spec + contents: [] + - section: "Bank Accounts" + referenced-packages: + - bankAccounts + contents: [] + ``` + + You can alternatively customize tag display names directly in your spec (or overlays file) using the [`x-displayName` extension](/api-definitions/openapi/extensions/tag-display-names). + + + + ```yaml title="docs.yml" {4-6} + navigation: + - api: API Reference + layout: + - section: "Billing" # New section display name + referenced-packages: + - billing # lowerCamelCase version of original service file name from your spec + contents: [] + - section: "Bank Accounts" + referenced-packages: + - bankAccounts + contents: [] + ``` + + + ```yaml title="docs.yml" + navigation: + - api: GraphQL API Reference + layout: + - section: Plants + contents: + - operation: QUERY getPlant + - operation: MUTATION createPlant + - section: Real-time + contents: + - operation: SUBSCRIPTION plantUpdates + ``` + + ### Flattening sections