Overview

Set up the Fern Folder

Configuring Fern starts with the fern folder, the root directory that contains your API definitions, generators, and your CLI version.

After you configure your fern folder, you’ll be ready to start generating SDKs in different languages.

Set up the fern folder

1

Install the Fern CLI

Run the following command to install the CLI tool or update it to the latest version:

$npm install -g fern-api
2

Initialize the Fern Folder

You can initialize your fern folder with either a Fern Definition or OpenAPI specification.

You can always convert a Fern Definition to OpenAPI or OpenAPI to a Fern Definition later on.

Initialize the fern folder using your OpenAPI Specification. Run one of the following commands based on your spec’s location.

Fern can handle both JSON and YML formats for OpenAPI specifications, and the —openapi flag accepts either format, so you can use whichever format your API spec is available in.

--organization <YourOrganization> configures your organization name in fern.config.json. This is required in order to successfully generate your SDK.

$fern init --openapi path/to/openapi.yml --organization <YourOrganization>

This creates a fern folder in your current directory with the OpenAPI Specification. The exact folder structure might look different depending on your initial input files.

$fern/
>  ├─ fern.config.json # root-level configuration
>  └─ api/ # your API
>    ├─ generators.yml # generators you're using
>    └─ openapi/
>      ├─ openapi.yml  # API-level configuration

  1. Initialize the fern folder using the Fern Definition by running the following command:

    $fern init --organization <YourOrganization>
    --organization <YourOrganization> configures your organization name in fern.config.json. This is required in order to successfully generate your SDK.

    This creates a fern folder in your current directory with the Fern Definition.

    $fern/
    >  ├─ fern.config.json # root-level configuration
    >  ├─ generators.yml # generators you're using
    >  └─ definition/
    >    ├─ api.yml  # API-level configuration
    >    └─ imdb.yml # endpoints, types, and errors
    imdb.yml contains an example movies API. If you’re just generating an SDK for test purposes, you can leave this file as it is. To generate an SDK for your own API instead of the example movies API, replace imdb.yml with your own endpoints, types, and errors before proceeding with the rest of this page.
3

Generate an SDK in your desired language

TypeScript logo
TypeScript
Python
Go
Java
.NET
PHP
Ruby

Learn more about the initialized files

Every initialized fern directory has:

  • A fern.config.json file
  • A generators.yml file

fern.config.json

This file stores the organization and the version of the Fern CLI that you are using.

1{
2    "organization": "imdb",
3    "version": "0.65.27"
4}

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

To upgrade the CLI, run fern upgrade. This will update the version field in fern.config.json

generators.yml

The generators.yml file specifies which SDKs Fern should generate from your API specification. For each generator, it specifies where the package is published and configures customizations like package metadata, output locations, and generation settings.

See the generators.yml reference page for more information.

Configure Multiple APIs

The fern folder can house multiple API definitions. Instead of placing your API definitions at the top level, you can nest them within an apis folder. Be sure to include a generators.yml file within each API folder that specifies the location of the API definition.

$fern/
>  ├─ fern.config.json
>  ├─ generators.yml
>  └─ apis/
>    └─ imdb/
>        ├─ generators.yml
>        └─ openapi/
>          ├─ openapi.yml
>    └─ disney/
>        ├─ generators.yml
>        └─ openapi/
>          ├─ openapi.yml