Overview

The Fern Folder

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

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

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.

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.

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.

1api: 
2  path: ./path/to/openapi.yml

Multiple APIs

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.

$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