fern-api · devalog · Sep 10, 2025 · Sep 10, 2025
diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx
@@ -20,6 +20,8 @@ fern/
     └─ spec-file.yml # API definition file
 ```
 
+## Core configuration files
+
 <Note> 
   Beyond the core files, you can optionally use an overrides file to customize your API definition without modifying the original spec. See [Overrides](/api-definitions/overview/overrides) for instructions.
 </Note>
@@ -41,26 +43,98 @@ determinism.
 
 ### `generators.yml`
 
-The `generators.yml` file includes information about where your API definition file is located. It also [configures the SDKs](/sdks/overview/project-structure) you're generating for your API. 
+The `generators.yml` file points to your API definition and [specifies which SDKs to generate](/sdks/overview/project-structure).
 
 ```yaml title="generators.yml"
-api:
-  specs:
-    - openapi: spec-file.yml 
+# Your API definition
+api: 
+  specs: 
+    - openapi: ./openapi-1.yml
+
+# SDK generators
+groups:
+  ts-sdk:
+    generators:
+      - name: fernapi/fern-typescript-sdk
+        version: <Markdown src="/snippets/version-number-ts.mdx"/>
+        github:
+          repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
 ```
 
 ### 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 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. 
+
+<Note>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.</Note>
+
+## Multiple APIs
+
+When working with multiple API definitions, you can organize them in two ways depending on your SDK generation needs.
+
+<AccordionGroup>
+<Accordion title="Separate SDKs for each API">
+
+Use this approach when each API should generate its own independent set of SDKs.
+
+```bash
+fern/
+  ├─ fern.config.json
+  └─ apis/
+    ├─ user-api/
+    │   ├─ generators.yml        # Configures user-api SDKs
+    │   └─ openapi.yml
+    └─ payments-api/
+        ├─ generators.yml        # Configures payments-api SDKs  
+        └─ openapi.yml
+```
+
+Each API must have its own `generators.yml` file:
 
-  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. 
+```yaml title="apis/user-api/generators.yml"
+api:
+  specs:
+    - openapi: openapi.yml
+groups:
+  ts-sdk:
+    generators:
+      - name: fernapi/fern-typescript-sdk
+        github:
+          repository: company/user-api-typescript
+```
+</Accordion>
+<Accordion title="Combined SDKs from multiple APIs">
 
+Use this approach to merge multiple APIs into a single set of SDKs.
 
-## Multiple API definitions
+```bash
+fern/
+  ├─ fern.config.json
+  ├─ generators.yml             # Single config for combined SDKs
+  ├─ user-api/
+  │   └─ openapi.yml
+  └─ payments-api/
+      └─ openapi.yml
+```
 
-<Markdown src="/snippets/multiple-apis.mdx" />
+List all APIs in a single `generators.yml`:
 
-### Docs configuration
+```yaml title="generators.yml"
+api: 
+  specs: 
+    - openapi: user-api/openapi.yml
+    - openapi: payments-api/openapi.yml
+```
 
-APIs in docs are specified by [setting the `api-name` property](/docs/api-references/generate-api-ref#include-more-than-one-api-reference).
+If your APIs have overlapping schema names, add namespaces:
 
+```yaml title="generators.yml"
+api: 
+  specs: 
+    - openapi: user-api/openapi.yml
+    - namespace: payments
+      openapi: payments-api/openapi.yml
+```
+</Accordion>
+</AccordionGroup>
diff --git a/fern/products/sdks/project-structure.mdx b/fern/products/sdks/project-structure.mdx
@@ -9,19 +9,24 @@ Before generating SDKs with Fern, set up the proper GitHub repository structure
 
 Fern recommends a multi-repository structure containing:
 
-- **Source repository**: Contains your API definitions and SDK generation configuration
-- **SDK repositories**: Separate repositories for each SDK (TypeScript, Python, Go, etc.)
+- **Source repository** with your API definitions and SDK generation configuration
+- **SDK repositories** for each SDK (TypeScript, Python, Go, etc.)
 
 ```bash
 ├─ company-repo                 # Source repository
-│  ├─ .github.workflows         # Contains publishing workflows for all SDKs
+│  ├─ .github/workflows/         # Publishing workflows for all SDKs
 │  └─ fern/
 │     ├─ fern.config.json       # Root-level config
 │     ├─ generators.yml         # References SDK repos
 │     └─ definition/ 
-         ├─ overrides.yml       # Optional overrides file
+│        ├─ overrides.yml       # Optional overrides file
 │        └─ api.yml             # Your API definition
 ├─ typescript-sdk-repo          # SDK repository
+│  ├─ .github/workflows/        # Generated by Fern
+│  ├─ scripts/
+│  ├─ src/
+│  ├─ tests/
+│  └─ .fernignore               # Files Fern shouldn't modify
 ├─ python-sdk-repo              # SDK repository  
 └─ go-sdk-repo                  # SDK repository
 ```
@@ -51,23 +56,29 @@ Every time you run a fern CLI command, the CLI downloads itself at the correct v
 
 ### `generators.yml`
 
-The `generators.yml` file specifies which SDKs to generate and where to publish them. It acts as the bridge between your API definitions and your SDK repositories. It contains a group for each SDK generator and points to the corresponding SDK's repository:
+The `generators.yml` file points to your API definition and specifies which SDKs to generate.
 
-```yaml
+```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: <Markdown src="/snippets/version-number-ts.mdx"/>
         github:
-          repository: your-organization/typescript-sdk-repo
+          repository: your-organization/typescript-sdk-repo # Location of TypeScript SDK
 
   python-sdk:
     generators:
       - name: fernapi/fern-python-sdk
         version: <Markdown src="/snippets/version-number-python.mdx"/>
         github:
-          repository: your-organization/python-sdk-repo
+          repository: your-organization/python-sdk-repo # Location of Python SDK
 ```
 
 <Info title="Examples"> 
@@ -78,34 +89,10 @@ See the [`generators.yml` reference page](/sdks/reference/generators-yml) for co
 
 ### API definition file
 
-For information on how to structure your API definition files, see [Project structure (API Definitions)](/api-definitions/overview/project-structure).
-
-### Optional: `overrides.yml` file
-
-You can optionally add an `overrides.yml` file to customize your API definition without modifying the original spec file. For more information, see [Overrides](/api-definitions/overview/overrides).
-
-## SDK repository structure
-
-Each SDK has its own repository with the following structure:
-
-```bash
-typescript-sdk-repo/            # Individual SDK repository
-├─ .github/workflows/           # Generated by Fern
-├─ scripts/
-├─ src/
-├─ tests/
-└─ .fernignore                  # Files Fern shouldn't modify
-```
-
-Fern generates most of these files automatically, including preserving any custom code you've added.
+See [Project structure (API Definitions)](/api-definitions/overview/project-structure) for details on organizing your API definition files and working with multiple APIs.
 
 ## Setup instructions
 
 1. **Create repositories**: Set up your source repository, plus one repository for each SDK
 2. **Install Fern GitHub App**: Install the [Fern GitHub App](https://github.com/apps/fern-api) on all repositories
-3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository.
-
-## Multiple API definitions
-
-<Markdown src="/snippets/multiple-apis.mdx" />
-
+3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository.
diff --git a/fern/snippets/multiple-apis.mdx b/fern/snippets/multiple-apis.mdx