Packages in Fern Definition

What is a package?

Every folder in your API definition is a package.

Example of package and nested package
$fern/
>├─ fern.config.json
>├─ generators.yml
>└─ definition/ # <--- root package
> ├─ api.yml
> ├─ projects.yml
> └─ roles/ # <--- nested package
> └─ admin.yml

The generated SDK will match the hierarchy of your API definition.

Generated SDK
1const client = new Client();
2
3// calling endpoint defined in projects.yml
4client.projects.get();
5
6// calling endpoint defined in roles/admin.yml
7client.roles.admin.get();

Package configuration

Each package can have a special definition file called __package__.yml. Like any other definition file, it can contain imports, types, endpoints, and errors.

Endpoints in __package__.yml will appear at the root of the package. For example, the following generated SDK:

Generated SDK
1const client = new Client();
2
3client.getProjects();

would have a fern/ folder:

fern/
$fern/
>├─ fern.config.json
>├─ generators.yml
>└─ definition/
> ├─ __package__.yml
> └─ roles.yml

that contains the following __package__.yml:

__package__.yml
1service:
2 base-path: ""
3 auth: false
4 endpoints:
5 getProjects:
6 method: GET
7 path: ""
8 response: list<Project>

Namespacing

Each package has its own namespace. This means you can reuse type names and error names across packages.

This is useful when versioning your APIs. For example, when you want to increment your API version, you can copy the existing API to a new package and start making changes. If the new API version reuses certain types or errors, that’s okay because the two APIs live in different packages.

Versioning example
$fern/
>├─ fern.config.json
>├─ generators.yml
>└─ definition/
> ├─ api.yml
> └─ roles/
> └─ v1/
> └─ admin.yml # type names can overlap with v2/admin.yml
> └─ v2/
> └─ admin.yml

__package__.yml also allows you to configure the navigation order of your services. This is relevant when you want to control the display of your documentation.

For example, let’s say you have the following fern/ folder:

fern/
$fern/
>├─ fern.config.json
>├─ generators.yml
>└─ definition/
> ├─ projects.yml
> ├─ roles.yml
> └─ users.yml

Your API will be sorted alphabetically: projects, roles, then users. If you want to control the navigation, you can add a __package__.yml file and configure the order:

fern/
$fern/
>├─ fern.config.json
>├─ generators.yml
>└─ definition/
> ├─ __package__.yml # <--- New File
> ├─ projects.yml
> ├─ roles.yml
> └─ users.yml
__package__.yml
1navigation:
2 - users.yml
3 - roles.yml
4 - projects.yml