Merging multiple API specs

Pro Feature

This feature is only available on paid plans. Please schedule a demo or email us to get started.

Fern supports intelligently merging multiple API Definitions into a single SDK. This feature is useful when you have multiple micro-services that you would like to expose as a single SDK.

You can specify your API Definition in generators.yml. In the normal case, you would have a single API Definition.

1api: path/to/petstore.yml

If you have multiple API Definitions, you can specify them in generators.yml as follows:

1api: 
2  - path/to/petstore.yml
3  - path/to/plantstore.yml

If you have multiple API Definitions that have overlapping schema names or operation names, you can specify a namespace for each API Definition. A namespace is often used to handle API versioning. Note these are nested under a namespaces block.

1api: 
2  namespaces:
3    v1: 
4      - path/to/petstore.yml
5      - path/to/plantstore.yml
6    v2: 
7      - path/to/petstore-v2.yml
8      - path/to/plantstore-v2.yml

Fern allows you to import other APIs into your API. This is often useful if:

  • you want to reuse another API’s types in your API
  • you want to combine multiple APIs into one SDK (similar to the AWS SDK)

This feature is only available if you use a Fern Definition.

1

Register your API

The first step is to register the API you want to depend on. To do this, use the register command:

$fern register
>  [some-dependency]: Uploading definition...
>  [some-dependency]: Registered @fern/some-dependency:0.0.1

You can set the version of your dependency by using the --version flag:

$fern register --version 1.0.0
>  [some-dependency]: Uploading definition...
>  [some-dependency]: Registered @fern/some-dependency:1.0.0
2

Depending on the registered API

To add a dependency on another API, you simply create a folder in your Fern Definition to “house” the dependency.

$fern/
>  ├─ fern.config.json
>  └─ api/ # <--- your API
>    ├─ generators.yml
>    └─ definition/
>      ├─ api.yml
>      ├─ imdb.yml
>      └─ my-folder
>        └─ __package__.yml

In __package__.yml, you can specify the API you want to depend on:

1export:
2name: @fern/some-dependency
3version: 0.0.1

At runtime, the __package__.yml file will effectively be replaced with the API you’re depending on.

Built with