From 84530f4b8fce8e452016b8b52cc351c08185c591 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 10 Nov 2025 23:18:49 +0000 Subject: [PATCH 1/8] Clarify generators.yml dual purpose: API declaration and code generation - Update OpenAPI and gRPC generators.yml reference pages to mention both SDKs and documentation - Add clarifying notes explaining generators.yml serves two roles: declaring APIs and configuring code generation - Update generators-yml-project-structure.mdx snippet to clarify dual purpose - Add note to docs product generate-api-ref.mdx explaining APIs must be declared in generators.yml - Update API definitions project-structure.mdx comment for consistency - Fix Vale style issues (capitalize API Reference, use contractions) Addresses user feedback that generators.yml appeared to be only for SDK generation, when it also declares APIs that can be rendered in documentation via docs.yml. Co-Authored-By: Devin Logan --- .../api-def/grpc-pages/reference/generators-reference.mdx | 6 +++++- .../openapi-pages/reference/generators-reference.mdx | 8 ++++++-- fern/products/api-def/pages/project-structure.mdx | 6 +++--- .../docs/pages/api-references/generate-api-ref.mdx | 4 ++++ fern/snippets/generators-yml-project-structure.mdx | 4 ++-- 5 files changed, 20 insertions(+), 8 deletions(-) diff --git a/fern/products/api-def/grpc-pages/reference/generators-reference.mdx b/fern/products/api-def/grpc-pages/reference/generators-reference.mdx index fd185f76c..c04698f4e 100644 --- a/fern/products/api-def/grpc-pages/reference/generators-reference.mdx +++ b/fern/products/api-def/grpc-pages/reference/generators-reference.mdx @@ -5,4 +5,8 @@ description: Reference for configuring gRPC specifications in your generators.ym Configure how your gRPC specification is processed and transformed into SDKs and documentation using the `generators.yml` configuration file. - \ No newline at end of file + + The `generators.yml` file serves two roles: it declares which APIs your project contains and configures code generation (for example, SDKs). The APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). + + + diff --git a/fern/products/api-def/openapi-pages/reference/generators-reference.mdx b/fern/products/api-def/openapi-pages/reference/generators-reference.mdx index 00dec2c86..521ded26d 100644 --- a/fern/products/api-def/openapi-pages/reference/generators-reference.mdx +++ b/fern/products/api-def/openapi-pages/reference/generators-reference.mdx @@ -3,6 +3,10 @@ title: OpenAPI generators.yml reference description: Reference for configuring OpenAPI specifications in your generators.yml file --- -Configure how your OpenAPI specification is processed and transformed into SDKs using the `generators.yml` configuration file. +Configure how your OpenAPI specification is processed and transformed into SDKs and documentation using the `generators.yml` configuration file. - \ No newline at end of file + + The `generators.yml` file serves two roles: it declares which APIs your project contains and configures code generation (for example, SDKs). The APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). + + + diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index 7ce0519cd..56e953cd9 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -15,7 +15,7 @@ When you run `fern init` (for the Fern Definition) or `fern init --spec-type pat ```bash fern/ ├─ fern.config.json # Root-level config for entire Fern project - ├─ generators.yml # Defines SDKs and docs to generate + ├─ generators.yml # Declares APIs and configures code generation └─ spec-folder/ # definition, openapi, asyncapi, etc. └─ spec-file.yml # API definition file ``` @@ -36,11 +36,11 @@ fern/ ### API definition file -For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What is a Fern Definition?](/api-definitions/ferndef/overview) for more information. +For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What's a Fern Definition?](/api-definitions/ferndef/overview) for more information. For the other specification formats ([OpenAPI](/api-definitions/openapi/overview), [AsyncAPI](/api-definitions/asyncapi/overview), [OpenRPC](/api-definitions/openrpc/overview), and [gRPC](/api-definitions/grpc/overview)), you'll have a single self-contained specification file. -To generate API reference documentation, [set the `api-name` property](/docs/api-references/generate-api-ref#include-more-than-one-api-reference) in your `docs.yml` file. +To generate API Reference documentation, [set the `api-name` property](/docs/api-references/generate-api-ref#include-more-than-one-api-reference) in your `docs.yml` file. ## Multiple APIs 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 9abc7d7bb..3e6d5a189 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -7,6 +7,10 @@ A key benefit of using Fern Docs is that once you've defined your API, you get y Add `- api: API Reference` to your navigation in `docs.yml` and Fern takes care of the rest! You'll see your endpoints, types, and cURL snippets automatically populated from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview). + + Your APIs must be declared in `generators.yml` before they can be rendered in your documentation. The `generators.yml` file serves two roles: it declares which APIs your project contains and configures code generation (for example, SDKs). See [OpenAPI generators.yml reference](/learn/api-definitions/openapi/generators-yml-reference). + + Example: ```yml docs.yml diff --git a/fern/snippets/generators-yml-project-structure.mdx b/fern/snippets/generators-yml-project-structure.mdx index cac0a7661..985fba2a6 100644 --- a/fern/snippets/generators-yml-project-structure.mdx +++ b/fern/snippets/generators-yml-project-structure.mdx @@ -1,4 +1,4 @@ -The `generators.yml` file specifies which SDKs to generate. **For OpenAPI**, it also points to the location of your spec. **For Fern Definition**, Fern automatically detects your spec when your `definition/` folder is at the same level as `generators.yml`. +The `generators.yml` file declares which APIs your project contains and configures code generation (for example, SDKs). The APIs declared here can also be rendered in your documentation. **For OpenAPI**, it points to the location of your spec. **For Fern Definition**, Fern automatically detects your spec when your `definition/` folder is at the same level as `generators.yml`. @@ -48,4 +48,4 @@ groups: repository: your-organization/python-sdk-repo # Location of Python SDK ``` - \ No newline at end of file + From 15f26f553c4442fe246be528db3fa738c71b7db0 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 12 Nov 2025 08:30:19 -0500 Subject: [PATCH 2/8] clarify info --- .../api-def/pages/project-structure.mdx | 6 +- .../pages/api-references/generate-api-ref.mdx | 32 +++++---- .../getting-started/project-structure.mdx | 66 ++++++++++--------- .../generators-yml-project-structure.mdx | 46 ++++++++----- 4 files changed, 87 insertions(+), 63 deletions(-) diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index 56e953cd9..712b8cd9e 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -15,7 +15,7 @@ When you run `fern init` (for the Fern Definition) or `fern init --spec-type pat ```bash fern/ ├─ fern.config.json # Root-level config for entire Fern project - ├─ generators.yml # Declares APIs and configures code generation + ├─ generators.yml # Declares APIs and configures SDK generation └─ spec-folder/ # definition, openapi, asyncapi, etc. └─ spec-file.yml # API definition file ``` @@ -36,12 +36,10 @@ fern/ ### API definition file -For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What's a Fern Definition?](/api-definitions/ferndef/overview) for more information. +For Fern Definition, your API configuration is split across two files: `api.yml` for API-wide configuration and separate `.yml` files for your actual endpoint and type definitions. See [What is a Fern Definition?](/api-definitions/ferndef/overview) for more information. For the other specification formats ([OpenAPI](/api-definitions/openapi/overview), [AsyncAPI](/api-definitions/asyncapi/overview), [OpenRPC](/api-definitions/openrpc/overview), and [gRPC](/api-definitions/grpc/overview)), you'll have a single self-contained specification file. -To generate API Reference documentation, [set the `api-name` property](/docs/api-references/generate-api-ref#include-more-than-one-api-reference) in your `docs.yml` file. - ## Multiple APIs When working with multiple API definitions, you can organize them in multiple ways depending on your SDK generation needs. 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 3e6d5a189..85cda9152 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -3,21 +3,23 @@ title: Generate your API Reference description: Use Fern Docs to generate your API Reference documentation from your API definition, using your choice of either OpenAPI or Fern Definition. --- -A key benefit of using Fern Docs is that once you've defined your API, you get your API Reference documentation with just one line. -Add `- api: API Reference` to your navigation in `docs.yml` and Fern takes care of the rest! You'll see your endpoints, types, -and cURL snippets automatically populated from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview). +Fern automatically generates your API Reference documentation from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview). Once you've set up your API definition, adding it to your docs takes just one line of configuration. - - Your APIs must be declared in `generators.yml` before they can be rendered in your documentation. The `generators.yml` file serves two roles: it declares which APIs your project contains and configures code generation (for example, SDKs). See [OpenAPI generators.yml reference](/learn/api-definitions/openapi/generators-yml-reference). - +**Prerequisites:** +- For **OpenAPI/AsyncAPI**: Add your spec file and create a `generators.yml` that references it in the `api.specs` section +- For **Fern Definition**: Add a `definition/` directory with your API definition files (Fern auto-detects this) -Example: +[Learn more about project structure](/learn/api-definitions/overview/project-structure). + +Add `- api: API Reference` to your navigation in `docs.yml`: ```yml docs.yml navigation: - api: API Reference ``` +Fern will automatically populate your endpoints, types, and code snippets from your API definition. + ### API Reference configuration options | Property | Value | @@ -40,18 +42,20 @@ More on customizing your API Reference [here](/learn/docs/api-references/customi ### Include more than one API Reference -To include multiple, distinct API definitions in your documentation, you can indicate which to include using the `api-name` property. The `api-name` corresponds to the name of the folder where your API definition is housed. +To include multiple, distinct API definitions in your documentation, use the `api-name` property. The `api-name` corresponds to the folder name containing your API definition. -For example, your file structure might look like this: +This works with any combination of OpenAPI and Fern Definition formats. For example: ```bash fern/ - ├─ fern.config.json + ├─ fern.config.json ├─ docs.yml - ├─ plant-api/ - │ └─ api.yml # API definition - └─ garden-api/ - └─ api.yml # API definition + ├─ 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/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx index 8aed6868e..844cb8436 100644 --- a/fern/products/docs/pages/getting-started/project-structure.mdx +++ b/fern/products/docs/pages/getting-started/project-structure.mdx @@ -1,5 +1,5 @@ --- -title: Project Structure +title: Project structure description: An overview of the file and folder structure of a Fern Docs project --- @@ -13,7 +13,8 @@ This page provides an overview of the file and folder structure of a Fern Docs p ├─ pages ├─ assets ├─ docs.yml - ├─ openapi + ├─ openapi # or definition/ for the Fern Definition + ├─ generators.yml └─ fern.config.json ``` @@ -22,8 +23,9 @@ A Fern Docs project has the following top-level folders: - `pages`: Contains the Markdown (MDX) files that make up your documentation. - `assets`: Contains any images or videos used in your documentation. -- `docs.yml`: The configuration file that defines the navigation, theme, and hosting details of your documentation. -- `openapi`: Contains the OpenAPI Specification file (if you have an API Reference section in your documentation). +- `docs.yml`: Defines the navigation, theme, and hosting details of your documentation. +- `openapi` or `definition/`: Contains your API specification files (if you have an API Reference section). +- `generators.yml`: Required for OpenAPI to reference your spec location. Also used to configure SDK generation. Not required for Fern Definition docs-only projects. - `fern.config.json`: The configuration file specifying your organization name and CLI version. ## Pages folder @@ -106,11 +108,26 @@ title: Fern's Documentation ``` -## API Definitions +## API definitions and `generators.yml` + +To generate [API Reference](/docs/api-references/generate-api-ref) documentation, you need to provide your API definition. How you do this depends on your format: + +- **OpenAPI/AsyncAPI**: Always requires a `generators.yml` file with an `api.specs` section. You can optionally add a `groups` section for SDK generation. +- **Fern Definition**: Auto-detected when you have a `definition/` directory. Only add `generators.yml` if you're generating SDKs. + +Using Fern for both API Reference docs and SDKs? You'll use `docs.yml` for your documentation settings and `generators.yml` to configure [SDK code snippets](/docs/api-references/sdk-snippets) in your API Reference. - The `openapi` folder contains the OpenAPI Specification file for your API Reference section. Fern will read either a YAML or JSON file from this folder to generate the API Reference documentation. If you don't have an API Reference section, you can skip this folder. + The `openapi` folder contains your OpenAPI Specification file. Fern supports either YAML or JSON format. + + You must also create a `generators.yml` file that references your spec: + + ```yaml title="generators.yml" + api: + specs: + - openapi: ../openapi/openapi.json + ``` In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. @@ -126,9 +143,9 @@ title: Fern's Documentation - The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. If you don't have an API Reference section, you can skip this folder. + The `definition` folder contains the Fern Definition YAML files used to generate the API Reference section. Fern automatically detects this directory, so no `generators.yml` is needed for API Reference documentation. - In addition to your specification file, you can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. + You can optionally [add an overrides file](/api-definitions/overview/overrides) for additional customizations. ```bash @@ -145,38 +162,27 @@ title: Fern's Documentation - If you have multiple APIs, you can organize them into separate folders within the `apis` folder. Each API should have its own API definition and [(optional) overrides file](/api-definitions/overview/overrides). - - For example: + Organize multiple APIs into separate folders. You can mix OpenAPI and Fern Definition formats: + ```bash apis - ├─ admin - │ ├─ openapi.json - │ └─ overrides.yaml - ├─ user - │ ├─ openapi.yaml - │ └─ overrides.yaml + ├─ admin-api + │ ├─ openapi.json + │ ├─ generators.yml # Required for OpenAPI + │ └─ overrides.yaml # Optional + └─ user-api + └─ definition/ # Auto-detected for Fern Definition + ├─ api.yml + └─ overrides.yaml # Optional ``` - To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). + Reference each API in `docs.yml` using `api-name` that matches the folder name. To see this in practice, check out [Vapi's Fern configuration](https://github.com/VapiAI/docs/tree/main/fern/apis). - - If you're using Fern for both API Reference documentation and SDKs, you'll use both `docs.yml` (the Docs configuration file) and `generators.yml` ([the SDK configuration file](/sdks/overview/project-structure#generatorsyml)) to configure [how SDK code snippets appear](/docs/api-references/sdk-snippets) in your API reference documentation. - - If you're only using Fern for API Reference docs, not SDKs, your `generators.yml` should simply link to your spec: - - ```yaml title="generators.yml" - api: - specs: - - openapi: ../openapi/openapi.json - ``` - - ## `fern.config.json` diff --git a/fern/snippets/generators-yml-project-structure.mdx b/fern/snippets/generators-yml-project-structure.mdx index 985fba2a6..e2583948f 100644 --- a/fern/snippets/generators-yml-project-structure.mdx +++ b/fern/snippets/generators-yml-project-structure.mdx @@ -1,13 +1,30 @@ -The `generators.yml` file declares which APIs your project contains and configures code generation (for example, SDKs). The APIs declared here can also be rendered in your documentation. **For OpenAPI**, it points to the location of your spec. **For Fern Definition**, Fern automatically detects your spec when your `definition/` folder is at the same level as `generators.yml`. +The `generators.yml` file serves two purposes: + +1. **API declaration** (OpenAPI/AsyncAPI only): References your spec in the `api.specs` section, which is required for [generating API Reference documentation](/learn/docs/api-references/generate-api-ref) +2. **SDK generation**: Configures which SDKs to generate in the `groups` section + +**For Fern Definition**, `generators.yml` is not required for API Reference docs. Fern automatically detects your API definition by checking for a `definition/` directory in your fern folder. You only need `generators.yml` if you're generating SDKs. - + + +For OpenAPI, `generators.yml` is required even for docs-only usage. The `api.specs` section tells Fern where to find your spec: + +```yaml title="generators.yml" +api: + specs: + - openapi: ./openapi/openapi.yml +``` + + + +To generate SDKs in addition to docs, add a `groups` section below your `api.specs`: ```yaml title="generators.yml" # Your API definition -api: - specs: - - openapi: ./openapi-1.yml +api: + specs: + - openapi: ./openapi/openapi.yml # SDK generators groups: @@ -16,36 +33,35 @@ groups: - name: fernapi/fern-typescript-sdk version: github: - repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK - + repository: your-organization/typescript-sdk-repo + python-sdk: generators: - name: fernapi/fern-python-sdk version: github: - repository: your-organization/python-sdk-repo # Location of Python SDK + repository: your-organization/python-sdk-repo ``` - + -```yaml title="generators.yml" -# No API reference needed – Fern auto-detects spec +For Fern Definition, `generators.yml` is only needed for SDK generation. API Reference docs work automatically when you have a `definition/` directory. -# SDK generators +```yaml title="generators.yml" groups: ts-sdk: generators: - name: fernapi/fern-typescript-sdk version: github: - repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK - + repository: your-organization/typescript-sdk-repo + python-sdk: generators: - name: fernapi/fern-python-sdk version: github: - repository: your-organization/python-sdk-repo # Location of Python SDK + repository: your-organization/python-sdk-repo ``` From 666f1718e5140eee87c82606177c6a704d2f4bbe Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 12 Nov 2025 08:31:25 -0500 Subject: [PATCH 3/8] fix vale --- fern/snippets/generators-yml-project-structure.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/snippets/generators-yml-project-structure.mdx b/fern/snippets/generators-yml-project-structure.mdx index e2583948f..33421aa12 100644 --- a/fern/snippets/generators-yml-project-structure.mdx +++ b/fern/snippets/generators-yml-project-structure.mdx @@ -3,7 +3,7 @@ The `generators.yml` file serves two purposes: 1. **API declaration** (OpenAPI/AsyncAPI only): References your spec in the `api.specs` section, which is required for [generating API Reference documentation](/learn/docs/api-references/generate-api-ref) 2. **SDK generation**: Configures which SDKs to generate in the `groups` section -**For Fern Definition**, `generators.yml` is not required for API Reference docs. Fern automatically detects your API definition by checking for a `definition/` directory in your fern folder. You only need `generators.yml` if you're generating SDKs. +**For Fern Definition**, `generators.yml` isn't required for API Reference docs. Fern automatically detects your API definition by checking for a `definition/` directory in your fern folder. You only need `generators.yml` if you're generating SDKs. @@ -18,7 +18,7 @@ api: -To generate SDKs in addition to docs, add a `groups` section below your `api.specs`: +To generate SDKs in addition to API Reference docs, add a `groups` section below your `api.specs`: ```yaml title="generators.yml" # Your API definition From 5156427800faf9faceae635f20565a9bd3faad37 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 12 Nov 2025 08:34:18 -0500 Subject: [PATCH 4/8] fix --- .../docs/pages/api-references/generate-api-ref.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 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 85cda9152..bfc2f2e70 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -5,11 +5,12 @@ description: Use Fern Docs to generate your API Reference documentation from you Fern automatically generates your API Reference documentation from your [OpenAPI Specification](/learn/api-definition/openapi/overview) or [Fern Definition](/learn/api-definition/fern/overview). Once you've set up your API definition, adding it to your docs takes just one line of configuration. -**Prerequisites:** -- For **OpenAPI/AsyncAPI**: Add your spec file and create a `generators.yml` that references it in the `api.specs` section -- For **Fern Definition**: Add a `definition/` directory with your API definition files (Fern auto-detects this) + + - For **OpenAPI/AsyncAPI**: Add your spec file and create a `generators.yml` that references it in the `api.specs` section + - For **Fern Definition**: Add a `definition/` directory with your API definition files (Fern auto-detects this) -[Learn more about project structure](/learn/api-definitions/overview/project-structure). + [Learn more about project structure](/learn/api-definitions/overview/project-structure). + Add `- api: API Reference` to your navigation in `docs.yml`: From 720733bd4716358ffb85ec540fdb4cdbc99d9e12 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 12 Nov 2025 08:47:30 -0500 Subject: [PATCH 5/8] clarify notes --- .../api-def/grpc-pages/reference/generators-reference.mdx | 6 +----- .../openapi-pages/reference/generators-reference.mdx | 6 +----- fern/products/sdks/reference/generators-yml-reference.mdx | 4 +--- 3 files changed, 3 insertions(+), 13 deletions(-) diff --git a/fern/products/api-def/grpc-pages/reference/generators-reference.mdx b/fern/products/api-def/grpc-pages/reference/generators-reference.mdx index c04698f4e..a50495978 100644 --- a/fern/products/api-def/grpc-pages/reference/generators-reference.mdx +++ b/fern/products/api-def/grpc-pages/reference/generators-reference.mdx @@ -3,10 +3,6 @@ title: gRPC generators.yml reference description: Reference for configuring gRPC specifications in your generators.yml file --- -Configure how your gRPC specification is processed and transformed into SDKs and documentation using the `generators.yml` configuration file. - - - The `generators.yml` file serves two roles: it declares which APIs your project contains and configures code generation (for example, SDKs). The APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). - +The `generators.yml` file serves two roles: it declares your gRPC specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). diff --git a/fern/products/api-def/openapi-pages/reference/generators-reference.mdx b/fern/products/api-def/openapi-pages/reference/generators-reference.mdx index 521ded26d..96c49ff01 100644 --- a/fern/products/api-def/openapi-pages/reference/generators-reference.mdx +++ b/fern/products/api-def/openapi-pages/reference/generators-reference.mdx @@ -3,10 +3,6 @@ title: OpenAPI generators.yml reference description: Reference for configuring OpenAPI specifications in your generators.yml file --- -Configure how your OpenAPI specification is processed and transformed into SDKs and documentation using the `generators.yml` configuration file. - - - The `generators.yml` file serves two roles: it declares which APIs your project contains and configures code generation (for example, SDKs). The APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). - +The `generators.yml` file serves two roles: it declares your OpenAPI specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 427b2a3a3..4c521fe66 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -4,9 +4,7 @@ description: Reference for the generators.yml configuration max-toc-depth: 3 --- -The `generators.yml` file configures how Fern generates SDKs from your API -specification, including which languages to generate, where to publish them, and -how to customize each SDK. +The `generators.yml` file serves two purposes: it declares your API definition (required for OpenAPI/AsyncAPI), and configures SDK generation, including which languages to generate, where to publish them, and how to customize each SDK. ```yaml title="generators.yml" maxLines=10 api: From c82855bc9559d878ad49bb1b9e148ac63479332a Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 12 Nov 2025 10:03:04 -0500 Subject: [PATCH 6/8] remove snippet for clarity --- .../reference/generators-reference.mdx | 4 +- .../reference/generators-reference.mdx | 4 +- .../api-def/pages/project-structure.mdx | 12 +++- fern/products/sdks/project-structure.mdx | 53 ++++++++++++++- .../generators-yml-project-structure.mdx | 67 ------------------- 5 files changed, 68 insertions(+), 72 deletions(-) delete mode 100644 fern/snippets/generators-yml-project-structure.mdx diff --git a/fern/products/api-def/grpc-pages/reference/generators-reference.mdx b/fern/products/api-def/grpc-pages/reference/generators-reference.mdx index a50495978..3181bc8a2 100644 --- a/fern/products/api-def/grpc-pages/reference/generators-reference.mdx +++ b/fern/products/api-def/grpc-pages/reference/generators-reference.mdx @@ -3,6 +3,8 @@ title: gRPC generators.yml reference description: Reference for configuring gRPC specifications in your generators.yml file --- -The `generators.yml` file serves two roles: it declares your gRPC specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). +The `generators.yml` file serves two roles: it declares your gRPC specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). + +APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). diff --git a/fern/products/api-def/openapi-pages/reference/generators-reference.mdx b/fern/products/api-def/openapi-pages/reference/generators-reference.mdx index 96c49ff01..b6a8139d8 100644 --- a/fern/products/api-def/openapi-pages/reference/generators-reference.mdx +++ b/fern/products/api-def/openapi-pages/reference/generators-reference.mdx @@ -3,6 +3,8 @@ title: OpenAPI generators.yml reference description: Reference for configuring OpenAPI specifications in your generators.yml file --- -The `generators.yml` file serves two roles: it declares your OpenAPI specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). +The `generators.yml` file serves two roles: it declares your OpenAPI specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). + +APIs declared here can be rendered in your documentation via `docs.yml`. See [Generate your API Reference](/learn/docs/api-references/generate-api-ref). diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index 712b8cd9e..c9065006f 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -32,7 +32,17 @@ fern/ ### `generators.yml` - +The `generators.yml` file is required for OpenAPI/AsyncAPI to declare your API specification location (which enables [API Reference documentation](/learn/docs/api-references/generate-api-ref)). It also optionally configures SDK generation. + +```yaml title="generators.yml" +api: + specs: + - openapi: ./openapi/openapi.yml +``` + +**For Fern Definition**, no `generators.yml` is needed to [generate API Reference docs](/learn/docs/api-references/generate-api-ref). Fern automatically detects your API by checking for a `definition/` directory. + +For SDK generation, `generators.yml` is required for all specification formats. Add a `groups` section to configure which SDKs to generate. See the [SDKs project structure](/sdks/overview/project-structure#generatorsyml) for details. ### API definition file diff --git a/fern/products/sdks/project-structure.mdx b/fern/products/sdks/project-structure.mdx index 1e9befc65..b9aeada87 100644 --- a/fern/products/sdks/project-structure.mdx +++ b/fern/products/sdks/project-structure.mdx @@ -47,9 +47,58 @@ The source repository contains a `fern/` folder that is initialized with your A ### `generators.yml` - +The `generators.yml` file configures SDK generation in the `groups` section. For OpenAPI/AsyncAPI, you must also declare your API spec location in the `api.specs` section. + +s + + +```yaml title="generators.yml" +# API declaration (required for OpenAPI/AsyncAPI) +api: + specs: + - openapi: ./openapi/openapi.yml + +# SDK generation +groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + github: + repository: your-organization/typescript-sdk-repo + + python-sdk: + generators: + - name: fernapi/fern-python-sdk + version: + github: + repository: your-organization/python-sdk-repo +``` + + + +For Fern Definition, the `api` section is not needed. Fern auto-detects your API from the `definition/` directory. + +```yaml title="generators.yml" +groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + version: + github: + repository: your-organization/typescript-sdk-repo + + python-sdk: + generators: + - name: fernapi/fern-python-sdk + version: + github: + repository: your-organization/python-sdk-repo +``` + + - + See Cohere's [`generators.yml` file](https://github.com/cohere-ai/cohere-developer-experience/blob/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern/apis/sdks/generators.yml) and Vapi's [`generators.yml` file](https://github.com/VapiAI/docs/blob/9c674c2b16ba03e864e26673c5290c88048c9a7a/fern/apis/api/generators.yml). diff --git a/fern/snippets/generators-yml-project-structure.mdx b/fern/snippets/generators-yml-project-structure.mdx deleted file mode 100644 index 33421aa12..000000000 --- a/fern/snippets/generators-yml-project-structure.mdx +++ /dev/null @@ -1,67 +0,0 @@ -The `generators.yml` file serves two purposes: - -1. **API declaration** (OpenAPI/AsyncAPI only): References your spec in the `api.specs` section, which is required for [generating API Reference documentation](/learn/docs/api-references/generate-api-ref) -2. **SDK generation**: Configures which SDKs to generate in the `groups` section - -**For Fern Definition**, `generators.yml` isn't required for API Reference docs. Fern automatically detects your API definition by checking for a `definition/` directory in your fern folder. You only need `generators.yml` if you're generating SDKs. - - - - -For OpenAPI, `generators.yml` is required even for docs-only usage. The `api.specs` section tells Fern where to find your spec: - -```yaml title="generators.yml" -api: - specs: - - openapi: ./openapi/openapi.yml -``` - - - -To generate SDKs in addition to API Reference docs, add a `groups` section below your `api.specs`: - -```yaml title="generators.yml" -# Your API definition -api: - specs: - - openapi: ./openapi/openapi.yml - -# SDK generators -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - github: - repository: your-organization/typescript-sdk-repo - - python-sdk: - generators: - - name: fernapi/fern-python-sdk - version: - github: - repository: your-organization/python-sdk-repo -``` - - - -For Fern Definition, `generators.yml` is only needed for SDK generation. API Reference docs work automatically when you have a `definition/` directory. - -```yaml title="generators.yml" -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - github: - repository: your-organization/typescript-sdk-repo - - python-sdk: - generators: - - name: fernapi/fern-python-sdk - version: - github: - repository: your-organization/python-sdk-repo -``` - - From 3a9dd39076c6ae419af81f5dd69b6b672edb7407 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 12 Nov 2025 10:06:55 -0500 Subject: [PATCH 7/8] fix --- fern/products/sdks/project-structure.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/sdks/project-structure.mdx b/fern/products/sdks/project-structure.mdx index b9aeada87..331adb3dc 100644 --- a/fern/products/sdks/project-structure.mdx +++ b/fern/products/sdks/project-structure.mdx @@ -49,7 +49,7 @@ The source repository contains a `fern/` folder that is initialized with your A The `generators.yml` file configures SDK generation in the `groups` section. For OpenAPI/AsyncAPI, you must also declare your API spec location in the `api.specs` section. -s + ```yaml title="generators.yml" From aeb2b88b54a5f512081c2601e3fa0039f766c28b Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Wed, 12 Nov 2025 10:12:04 -0500 Subject: [PATCH 8/8] fix vale and nit --- fern/products/api-def/pages/project-structure.mdx | 2 +- fern/products/sdks/project-structure.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index c9065006f..f3374d78f 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -32,7 +32,7 @@ fern/ ### `generators.yml` -The `generators.yml` file is required for OpenAPI/AsyncAPI to declare your API specification location (which enables [API Reference documentation](/learn/docs/api-references/generate-api-ref)). It also optionally configures SDK generation. +The `generators.yml` file is required for OpenAPI/AsyncAPI to declare your API specification location. This also enables [API Reference documentation](/learn/docs/api-references/generate-api-ref). ```yaml title="generators.yml" api: diff --git a/fern/products/sdks/project-structure.mdx b/fern/products/sdks/project-structure.mdx index 331adb3dc..8424c7316 100644 --- a/fern/products/sdks/project-structure.mdx +++ b/fern/products/sdks/project-structure.mdx @@ -77,7 +77,7 @@ groups: -For Fern Definition, the `api` section is not needed. Fern auto-detects your API from the `definition/` directory. +For Fern Definition, the `api` section isn't needed. Fern auto-detects your API from the `definition/` directory. ```yaml title="generators.yml" groups: