diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index a79cc5214..ca8a74ef5 100644 --- 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 + 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. @@ -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: + 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. + +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 two ways depending on your SDK generation needs. + + + + +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 +``` + + +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 +``` - +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 +``` + + \ No newline at end of file diff --git a/fern/products/sdks/project-structure.mdx b/fern/products/sdks/project-structure.mdx index 283e406f6..4b91eb1cb 100644 --- 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: 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: github: - repository: your-organization/python-sdk-repo + repository: your-organization/python-sdk-repo # Location of Python SDK ``` @@ -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 - - - +3. **Configure `generators.yml`**: In your `generators.yml`, add a reference to each SDK repository. \ No newline at end of file diff --git a/fern/snippets/multiple-apis.mdx b/fern/snippets/multiple-apis.mdx deleted file mode 100644 index 93554ef3c..000000000 --- a/fern/snippets/multiple-apis.mdx +++ /dev/null @@ -1,20 +0,0 @@ -The fern folder can house multiple API definitions. When you have multiple APIs, nest your definition files within a top-level `apis` folder. - -Each API must have a separate `generators.yml` file that specifies the location of the API definition and configures SDK generation. - -Below is an example of what a fern folder containing multiple APIs might look like. Your exact structure might vary depending on your organization's conventions and needs – the important part is that each API has its own `generators.yml` file. - -```bash -fern/ - ├─ fern.config.json - ├─ generators.yml # Optional: top-level configuration for all APIs - └─ apis/ - └─ first-api/ # First API - └─ spec-folder/ # definition, openapi, asyncapi, etc. - ├─ generators.yml # Required: points to API spec and configures SDKs - └─ spec-file.yml # API Definition file - └─ second-api/ # Second API - └─ spec-folder/ # definition, openapi, asyncapi, etc. - ├─ generators.yml # Required: points to API spec and configures SDKs - └─ spec-file.yml # API Definition file -``` \ No newline at end of file