Project structure
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:
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.
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 includes information about where your API definition file is located. It also configures the SDKs you’re generating for your API.
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.
Multiple API definitions
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.
Docs configuration
APIs in docs are specified by setting the api-name
property.