diff --git a/fern/products/api-def/pages/project-structure.mdx b/fern/products/api-def/pages/project-structure.mdx index ad2c09bd5..96fe64d8c 100644 --- a/fern/products/api-def/pages/project-structure.mdx +++ b/fern/products/api-def/pages/project-structure.mdx @@ -1,5 +1,5 @@ --- -title: The Fern Folder +title: Project structure description: Describes the Fern folder structure --- @@ -15,22 +15,15 @@ fern/ ├─ fern.config.json # Root-level config for entire Fern project ├─ generators.yml # Defines SDKs and docs to generate └─ spec-folder/ # definition, openapi, asyncapi, etc. - └─ spec-file.yml # API specification file + └─ spec-file.yml # 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 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. - - - - +### `fern.config.json file` Every fern folder has a single `fern.config.json` file. This file stores the organization and the version of the Fern CLI that you are using. -```json +```json title="fern.config.json" { "organization": "your-organization", "version": "0.31.2" @@ -39,35 +32,22 @@ the version of the Fern CLI that you are using. Every time you run a fern CLI command, the CLI downloads itself at the correct version to ensure determinism. - - -The `generators.yml` file includes information about where your API definition file is located. It also configures the SDKs you're generating for your API. +### `generators.yml` + +The `generators.yml` file includes information about where your API definition file is located. It also [configures the SDKs](/sdks/overview/github) you're generating for your API. -```yaml +```yaml title="generators.yml" api: path: ./path/to/openapi.yml ``` - - -## Multiple APIs +### API definition file -The fern folder can house multiple API definitions. When you have multiple APIs, nest your definition files within an `apis` folder. + 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. -Each API must also have a separate `generators.yml` file that specifies the location of the API definition and configures SDK generation. + 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. -```bash -fern/ - ├─ fern.config.json - ├─ generators.yml # Optional: top-level configuration for all APIs - └─ apis/ - └─ first-api/ # First API - ├─ generators.yml # Required: points to API spec - └─ openapi/ - ├─ openapi.yml # API Definition file - └─ second-api/ # Second API - ├─ generators.yml # Required: points to API spec - └─ openapi/ - ├─ openapi.yml # API Definition file -``` +## Multiple API definitions + + diff --git a/fern/products/sdks/github-setup.mdx b/fern/products/sdks/github-setup.mdx index d9f3a4a88..1126259a4 100644 --- a/fern/products/sdks/github-setup.mdx +++ b/fern/products/sdks/github-setup.mdx @@ -15,10 +15,10 @@ Fern recommends a parent-child repository structure containing: ```bash ├─ company-repo # Parent repository │ └─ fern/ -│ ├─ fern.config.json -│ ├─ apis/ -│ │ └─ sdks/ -│ │ └─ generators.yml # References child repos +│ ├─ fern.config.json # Root-level config +│ ├─ generators.yml # References child repos +│ └─ definition/ # or openapi/, asyncapi/, etc. +│ └─ api.yml # Your API definition ├─ typescript-sdk-repo # Child repository ├─ python-sdk-repo # Child repository └─ go-sdk-repo # Child repository @@ -26,17 +26,17 @@ Fern recommends a parent-child repository structure containing: This separation allows you to manage API definitions centrally while keeping each SDK in its own repository for independent versioning and distribution. - - For an example of this structure, see Cohere's [fern folder](https://github.com/cohere-ai/cohere-developer-experience/tree/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern) and [TypeScript](https://github.com/cohere-ai/cohere-typescript) and [Python](https://github.com/cohere-ai/cohere-python) child repositories. + + See Cohere's [fern folder](https://github.com/cohere-ai/cohere-developer-experience/tree/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern) and [TypeScript](https://github.com/cohere-ai/cohere-typescript) and [Python](https://github.com/cohere-ai/cohere-python) child repositories. ## Core configuration files -[Initializing your `fern` folder](/sdks/overview/quickstart) creates two key configuration files: +The parent repository contains a `fern/` folder that is initialized with your API definitions and a top-level `generators.yml` file. ### `fern.config.json` -This file stores your organization name and Fern CLI version: +Every fern folder has a single `fern.config.json` file. This file stores the organization name and the version of the Fern CLI that you are using: ```json { @@ -45,40 +45,13 @@ This file stores your organization name and Fern CLI version: } ``` -### `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. - - -For examples, 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). - - +Every time you run a fern CLI command, the CLI downloads itself at the correct version to ensure determinism. - - See the [`generators.yml` reference page](/sdks/reference/generators-yml) for complete configuration options. - - -## Parent repository structure - -The parent repository contains your API definitions and the `generators.yml` file that references your child SDK repositories. - - -```bash -company-repo/ -├─ fern/ -│ ├─ fern.config.json -│ ├─ apis/ -│ │ └─ sdks/ -│ │ └─ generators.yml # SDK generation configuration -``` - +### `generators.yml` -Your `generators.yml` file contains a group for each SDK and points to the corresponding child repository: +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. For SDK generation, it contains a group for each SDK and points to the corresponding child repository: -```yaml title="generators.yml" +```yaml groups: ts-sdk: generators: @@ -95,11 +68,20 @@ groups: 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). + + +See the [`generators.yml` reference page](/sdks/reference/generators-yml) for complete configuration options. + +### API definition file + +For information on how to structure your API definition files, see [Project structure (API Definitions)](/api-definitions/overview/project-structure). + ## Child repository structure Each SDK has its own repository with the following structure: - ```bash typescript-sdk-repo/ # Individual SDK repository ├─ .github/workflows/ # Publishing workflows @@ -108,7 +90,6 @@ typescript-sdk-repo/ # Individual SDK repository ├─ tests/ └─ .fernignore # Files Fern shouldn't modify ``` - Fern generates most of these files automatically, including preserving any custom code you've added. @@ -120,41 +101,5 @@ Fern generates most of these files automatically, including preserving any custo ## Multiple API definitions -For multiple APIs, organize them in separate folders within the `apis` directory: + - - -```bash -fern/ - ├─ fern.config.json - ├─ generators.yml - └─ apis/ - └─ imdb/ - ├─ generators.yml - └─ openapi/ - ├─ openapi.yml - └─ disney/ - ├─ generators.yml - └─ openapi/ - ├─ openapi.yml -``` - - -```bash -fern/ - ├─ fern.config.json - ├─ generators.yml - └─ apis/ - └─ imdb/ - ├─ generators.yml - └─ definition/ - ├─ api.yml - └─ imdb.yml - └─ disney/ - ├─ generators.yml - └─ definition/ - ├─ api.yml - └─ disney.yml -``` - - \ No newline at end of file diff --git a/fern/snippets/multiple-apis.mdx b/fern/snippets/multiple-apis.mdx new file mode 100644 index 000000000..2bbe1b952 --- /dev/null +++ b/fern/snippets/multiple-apis.mdx @@ -0,0 +1,18 @@ +The fern folder can house multiple API definitions. When you have multiple APIs, nest your definition files within an `apis` folder. + +Each API must also have a separate `generators.yml` file that specifies the location of the API definition and configures SDK generation. + +```bash +fern/ + ├─ fern.config.json + ├─ generators.yml # Optional: top-level configuration for all APIs + └─ apis/ + └─ first-api/ # First API + ├─ generators.yml # Required: points to API spec + └─ openapi/ + ├─ openapi.yml # API Definition file + └─ second-api/ # Second API + ├─ generators.yml # Required: points to API spec + └─ openapi/ + ├─ openapi.yml # API Definition file +``` \ No newline at end of file