Project structure | Fern Documentation

Configuring fern starts with the fern folder, which contains your API definitions, SDK generators, and your CLI version.

Fern recommends a multi-repository structure with your fern folder in a source repository (containing your API definitions and generation configuration) and each generated SDK in its own separate repository.

Directory structure

When you run fern init (for the Fern Definition) or fern init --spec-type path/to/spec (for other specs), your fern folder is initialized with the following files:

$ 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 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 for instructions.

`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.

fern.config.json

1 {
2     "organization": "your-organization",
3     "version": "0.31.2"
4 }

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

`generators.yml`

The generators.yml file points to your API definition and specifies which SDKs to generate.

generators.yml

1 # Your API definition
2 api: 
3   specs: 
4     - openapi: ./openapi-1.yml
5 
6 # SDK generators
7 groups:
8   ts-sdk:
9     generators:
10       - name: fernapi/fern-typescript-sdk
11         version: 2.12.3
12         github:
13           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? for more information.

For the other specification formats (OpenAPI, AsyncAPI, OpenRPC, and gRPC), you’ll have a single self-contained specification file.

To generate API reference documentation, set the api-name property 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.

Separate SDKs for each API

Use this approach when each API should generate its own independent set of SDKs.

$ 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:

apis/user-api/generators.yml

1 api:
2   specs:
3     - openapi: openapi.yml
4 groups:
5   ts-sdk:
6     generators:
7       - name: fernapi/fern-typescript-sdk
8         github:
9           repository: company/user-api-typescript

Combined SDKs from multiple APIs

Use this approach to merge multiple APIs into a single set of SDKs.

$ 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:

generators.yml

1 api: 
2   specs: 
3     - openapi: user-api/openapi.yml
4     - openapi: payments-api/openapi.yml

If your APIs have overlapping schema names, add namespaces:

generators.yml

1 api: 
2   specs: 
3     - openapi: user-api/openapi.yml
4     - namespace: payments
5       openapi: payments-api/openapi.yml