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).
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
.
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:
Get started here.
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>
Generator ID | Latest Version | Changelog | Entrypoint |
---|---|---|---|
fernapi/fern-typescript-node-sdk |
0.12.8 |
CHANGELOG.md | cli.ts |
fernapi/fern-python-sdk |
0.12.4 |
CHANGELOG.md | cli.py |
fernapi/fern-java-sdk |
0.8.6 |
CHANGELOG.md | Cli.java |
fernapi/fern-ruby-sdk |
0.3.2 |
CHANGELOG.md | cli.ts |
fernapi/fern-go-sdk |
0.18.0 |
CHANGELOG.md | main.go |
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. Watch a demo here.
Generator ID | Latest Version | Changelog | Entrypoint |
---|---|---|---|
fernapi/fern-typescript-express |
0.12.8 |
CHANGELOG.md | cli.ts |
fernapi/fern-fastapi-server |
0.12.4 |
CHANGELOG.md | cli.py |
fernapi/fern-java-spring |
0.8.6 |
CHANGELOG.md | Cli.java |
Fern's model generators will output schemas or types defined in your OpenAPI spec or Fern Definition.
Generator ID | Latest Version | Changelog | Entrypoint |
---|---|---|---|
fernapi/fern-pydantic-model |
0.12.8 |
CHANGELOG.md | cli.py |
fernapi/fern-java-model |
0.8.6 |
CHANGELOG.md | Cli.java |
fernapi/fern-ruby-model |
0.3.2 |
CHANGELOG.md | cli.ts |
Fern's spec generators can output an OpenAPI spec or a Postman collection.
Note: The OpenAPI spec generator is primarly intended for Fern Definition users. This prevents lock-in so that one can always export to OpenAPI.
Generator ID | Latest Version | Changelog | Entrypoint |
---|---|---|---|
fernapi/fern-openapi |
0.0.30 |
CHANGELOG.md | cli.ts |
fernapi/fern-postman |
0.1.0 |
CHANGELOG.md | cli.ts |
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
.
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:
For a walkthrough, check out the Fern + Express video.
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:
Join our Discord! We are here to answer questions and help you get the most out of Fern.
We welcome community contributions. For guidelines, refer to our CONTRIBUTING.md.