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:

npm install -g fern-api

Initialize Fern with your OpenAPI spec:

fern init --openapi ./path/to/openapi.yml
# or
fern init --openapi https://link.buildwithfern.com/petstore-openapi

Your directory should look like the following:

fern/
├─ fern.config.json
├─ generators.yml # generators you're using
└─ openapi/
  └─ openapi.json # your openapi document

Finally, to invoke the generator, run:

fern 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

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.

npm install -g fern-api
fern init

This will create the following folder structure in your project:

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

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

types:
  MovieId: string

  Movie:
    properties:
      id: MovieId
      title: string
      rating:
        type: double
        docs: The rating scale is one to five stars

  CreateMovieRequest:
    properties:
      title: string
      rating: double

service:
  auth: false
  base-path: /movies
  endpoints:
    createMovie:
      docs: Add a movie to the database
      method: POST
      path: /create-movie
      request: CreateMovieRequest
      response: MovieId

    getMovie:
      method: GET
      path: /{movieId}
      path-parameters:
        movieId: MovieId
      response: Movie
      errors:
        - MovieDoesNotExistError

errors:
  MovieDoesNotExistError:
    status-code: 404
    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 Discord! 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.