armandobelardo / fern Goto Github PK

Fern is an open-source toolkit that simplifies the design, build, and consumption of REST APIs. It allows you to effortlessly generate SDKs, API documentation, and backend server boilerplate.

Note: Fern requires Node 18 or higher

The Fern toolkit is available as a command line interface (CLI). To install it, run:

npm install -g fern-api

To create a starter project, navigate to the root of your repository and run:

fern init

This will initialize a Fern workspace in the current folder, including the ./fern directory that Fern will use to hold its resources.

Note: to initialize a starter project from an existing OpenAPI spec, see Starting from OpenAPI.

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

If you have an existing OpenAPI definition, you can use that as your starting point by specifying the --openapi option:

fern init --openapi ./path/to/openapi.yml
# or
fern init --openapi https://petstore.swagger.io/v2/swagger.json

This will generate an OpenAPI-based Fern project:

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

REST APIs underpin the internet but are still painful to work with. They are often untyped, unstandardized, and out-of-sync across multiple sources of truth. With Fern, we aim to bring great developer experiences to REST APIs.

Fern is fully compatible with OpenAPI, allowing the use of existing OpenAPI specifications. It's designed to augment, not replace, your current OpenAPI toolchains and workflows.

The Fern CLI can generate the following types of artifacts:

Generate idiomatic SDKs (client libraries). Fern keeps your SDKs synchronized with your backend, eliminating the need to manually maintain your SDKs as your API changes. Fern can publish your SDKs to registries, like npm, Maven, and PyPI.

Currently, the following languages are supported:

• TypeScript
• Java
• Python
• Go

For additional language support, visit the Fern issues and let us know!

Fern will 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.propexo.com

Define your API, and Fern will 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

For a walkthrough, check out the Fern + Express video.

See how developer-focused companies benefit from Fern.

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.

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

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.