Skip to content

Align SDKs and API Definitions project structure pages #485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 18, 2025
+55 −112
Merged

Align SDKs and API Definitions project structure pages #485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39b81f7
align sdk and api def project structure pages
devalog Aug 18, 2025
c48f5d9
nit formatting
devalog Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 14 additions & 34 deletions fern/products/api-def/pages/project-structure.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: The Fern Folder
title: Project structure
description: Describes the Fern folder structure
---

Expand All @@ -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
```

<Info>
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.
</Info>

<AccordionGroup>
<Accordion title="What is the fern.config.json 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"
Expand All @@ -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.
</Accordion>
<Accordion title="What is the generators.yml file?">

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
```
</Accordion>
</AccordionGroup>

## 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

<Markdown src="/snippets/multiple-apis.mdx" />
101 changes: 23 additions & 78 deletions fern/products/sdks/github-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,28 +15,28 @@ 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
```

This separation allows you to manage API definitions centrally while keeping each SDK in its own repository for independent versioning and distribution.

<Info>
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.
<Info title="Examples">
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.
</Info>

## 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
{
Expand All @@ -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.

<Info>
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).
</Info>

Every time you run a fern CLI command, the CLI downloads itself at the correct version to ensure determinism.

<Info>
See the [`generators.yml` reference page](/sdks/reference/generators-yml) for complete configuration options.
</Info>

## Parent repository structure

The parent repository contains your API definitions and the `generators.yml` file that references your child SDK repositories.

<CodeBlock title="Parent repository structure">
```bash
company-repo/
├─ fern/
│ ├─ fern.config.json
│ ├─ apis/
│ │ └─ sdks/
│ │ └─ generators.yml # SDK generation configuration
```
</CodeBlock>
### `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:
Expand All @@ -95,11 +68,20 @@ groups:
repository: your-organization/python-sdk-repo
```

<Info title="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).
</Info>

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:

<CodeBlock title="Child repository structure">
```bash
typescript-sdk-repo/ # Individual SDK repository
├─ .github/workflows/ # Publishing workflows
Expand All @@ -108,7 +90,6 @@ typescript-sdk-repo/ # Individual SDK repository
├─ tests/
└─ .fernignore # Files Fern shouldn't modify
```
</CodeBlock>

Fern generates most of these files automatically, including preserving any custom code you've added.

Expand All @@ -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:
<Markdown src="/snippets/multiple-apis.mdx" />

<Tabs>
<Tab title="OpenAPI Definition">
```bash
fern/
├─ fern.config.json
├─ generators.yml
└─ apis/
└─ imdb/
├─ generators.yml
└─ openapi/
├─ openapi.yml
└─ disney/
├─ generators.yml
└─ openapi/
├─ openapi.yml
```
</Tab>
<Tab title="Fern Definition">
```bash
fern/
├─ fern.config.json
├─ generators.yml
└─ apis/
└─ imdb/
├─ generators.yml
└─ definition/
├─ api.yml
└─ imdb.yml
└─ disney/
├─ generators.yml
└─ definition/
├─ api.yml
└─ disney.yml
```
</Tab>
</Tabs>
18 changes: 18 additions & 0 deletions fern/snippets/multiple-apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```