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..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 --- -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 your gRPC specification location (in the `api.specs` section), and configures SDK generation (in the optional `groups` section). - \ No newline at end of file +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..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 --- -Configure how your OpenAPI specification is processed and transformed into SDKs using the `generators.yml` configuration 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). - \ No newline at end of file +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..f3374d78f 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 SDK generation └─ spec-folder/ # definition, openapi, asyncapi, etc. └─ spec-file.yml # API definition file ``` @@ -32,7 +32,17 @@ fern/ ### `generators.yml` - +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: + 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 @@ -40,8 +50,6 @@ For Fern Definition, your API configuration is split across two files: `api.yml` 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 9abc7d7bb..bfc2f2e70 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -3,17 +3,24 @@ 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. -Example: + + - 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). + + +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 | @@ -36,18 +43,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/products/sdks/project-structure.mdx b/fern/products/sdks/project-structure.mdx index 1e9befc65..8424c7316 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. + + + + +```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 isn't 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/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: diff --git a/fern/snippets/generators-yml-project-structure.mdx b/fern/snippets/generators-yml-project-structure.mdx deleted file mode 100644 index cac0a7661..000000000 --- a/fern/snippets/generators-yml-project-structure.mdx +++ /dev/null @@ -1,51 +0,0 @@ -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`. - - - - -```yaml title="generators.yml" -# Your API definition -api: - specs: - - openapi: ./openapi-1.yml - -# SDK generators -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - github: - repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK - - python-sdk: - generators: - - name: fernapi/fern-python-sdk - version: - github: - repository: your-organization/python-sdk-repo # Location of Python SDK -``` - - - -```yaml title="generators.yml" -# No API reference needed – Fern auto-detects spec - -# SDK generators -groups: - ts-sdk: - generators: - - name: fernapi/fern-typescript-sdk - version: - github: - repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK - - python-sdk: - generators: - - name: fernapi/fern-python-sdk - version: - github: - repository: your-organization/python-sdk-repo # Location of Python SDK -``` - - \ No newline at end of file