Fern is a toolkit that allows you to input your API Definition and output SDKs and API documentation. Fern is compatible with the OpenAPI specification (formerly Swagger).

🌿 SDKs

The Fern toolkit is available via a command line interface (CLI) and requires Node 18+. To install it, run:

1npm install -g fern-api

Initialize Fern with your OpenAPI spec:

1fern init --openapi ./path/to/openapi.yml
2# or
3fern init --openapi https://link.buildwithfern.com/plantstore-openapi

Your directory should look like the following:

1fern/
2├─ fern.config.json
3├─ generators.yml # generators you're using
4└─ openapi/
5  └─ openapi.json # your openapi document

Finally, to invoke the generator, run:

1fern generate

🎉 Once the command completes, you'll see your SDK in /generated/sdks/typescript.

🌿 API Documentation

Fern can also build and host a documentation website with an auto-generated API reference. Write additional pages in markdown and have them versioned with git. Search, SEO, dark mode, and popular components are provided out-of-the-box. Plus, you can customize the colors, font, logo, and domain name.

Check out docs built with Fern:

• docs.vellum.ai
• docs.superagent.sh
• docs.hume.ai
• docs.deepgram.com

Get started here.

🌿 Generators

Generators are process that take your API Definition as input and output artifacts (SDKs, Postman Collections, Server boilerplate, etc.). To add a generator run fern add <generator id>

SDK Generators

Generator ID	Latest Version	Entrypoint
fernapi/fern-typescript-node-sdk		cli.ts
fernapi/fern-python-sdk		cli.py
fernapi/fern-java-sdk		Cli.java
fernapi/fern-ruby-sdk		cli.ts
fernapi/fern-go-sdk		main.go
fernapi/fern-csharp-sdk		cli.ts
fernapi/fern-php-sdk		cli.ts

Server-side Generators

Fern's server-side generators output boilerplate application code (models and networking logic). This is intended for spec-first or API-first developers, who write their API definition (as an OpenAPI spec or Fern definition) and want to generate backend code.

Generator ID	Latest Version	Entrypoint
fernapi/fern-typescript-express		cli.ts
fernapi/fern-fastapi-server		cli.py
fernapi/fern-java-spring		Cli.java

Model Generators

Fern's model generators will output schemas or types defined in your OpenAPI spec or Fern Definition.

Generator ID	Latest Version	Entrypoint
fernapi/fern-pydantic-model		cli.py
fernapi/java-model		Cli.java
fernapi/fern-ruby-model		cli.ts
fernapi/fern-go-model		main.go

Spec Generators

Fern's spec generators can output an OpenAPI spec or a Postman collection.

Note: The OpenAPI spec generator is primarily intended for Fern Definition users. This prevents lock-in so that one can always export to OpenAPI.

Generator ID	Latest Version	Entrypoint
fernapi/fern-openapi		cli.ts
fernapi/fern-postman		cli.ts

🌿 CLI Commands

Here's a quick look at the most popular CLI commands. View the documentation for all CLI commands.

fern init: adds a new starter API to your repository.

fern check: validate your API definition and Fern configuration.

fern generate: run the generators specified in generators.yml in the cloud.

fern generate --local: run the generators specified in generators.yml in docker locally.

fern add <generator>: include a new generator in your generators.yml. For example, fern add fern-python-sdk.

Advanced

API First

Fern supports developers and teams that want to be API-first or Spec-first.

Define your API, and use Fern to generate models, networking code and boilerplate application code. The generated code adds type safety to your API implementation - if your backend doesn't implement the API correctly, it won't compile.

Frameworks currently supported:

• Express
• Spring Boot
• FastAPI

Fern Definition

While we are big fans of OpenAPI, we know it isn't the easiest format to read and write. If you're looking for an alternative, give the Fern Definition a try.

Install the Fern CLI and initialize a Fern Project.

1npm install -g fern-api
2fern init

This will create the following folder structure in your project:

1fern/
2├─ fern.config.json # root-level configuration
3├─ generators.yml # generators you're using
4└─ definition/
5  ├─ api.yml  # API-level configuration
6  └─ imdb.yml # endpoints, types, and errors

Here's what the imdb.yml starter file looks like:

1types:
2  MovieId: string
3
4  Movie:
5    properties:
6      id: MovieId
7      title: string
8      rating:
9        type: double
10        docs: The rating scale is one to five stars
11
12  CreateMovieRequest:
13    properties:
14      title: string
15      rating: double
16
17service:
18  auth: false
19  base-path: /movies
20  endpoints:
21    createMovie:
22      docs: Add a movie to the database
23      method: POST
24      path: /create-movie
25      request: CreateMovieRequest
26      response: MovieId
27
28    getMovie:
29      method: GET
30      path: /{movieId}
31      path-parameters:
32        movieId: MovieId
33      response: Movie
34      errors:
35        - MovieDoesNotExistError
36
37errors:
38  MovieDoesNotExistError:
39    status-code: 404
40    type: MovieId

Checkout open source projects that are using Fern Definitions:

• Metriport
• Rivet

Inspiration

Fern is inspired by internal tooling built to enhance the developer experience. We stand on the shoulders of giants. While teams were responsible for building the following tools, we want to give a shout out to Mark Elliot (creator of Conjure at Palantir), Michael Dowling (creator of Smithy at AWS), and Ian McCrystal (creator of Stripe Docs).

Community

Join our Slack! We are here to answer questions and help you get the most out of Fern.

Contributing

We welcome community contributions. For guidelines, refer to our CONTRIBUTING.md.