什么是 Fern Definition？ | Fern Documentation

Fern Definition 是一组 YAML 文件，它们是你 API 的单一源头。你将 Fern Definition 检入到你的代码仓库中，在其中描述你的 API 请求、响应、模型、路径、方法、错误和身份验证方案。

Fern Definition 结构

要初始化一个 Fern Definition，只需运行：

npm install -g fern-api
fern init

这将在你的项目中创建以下文件夹结构：

fern

fern.config.json# 根级配置

generators.yml# 你正在使用的生成器

definition

api.yml# API 级配置

imdb.yml# 端点、类型和错误

Definition 文件

每个 Fern Definition 文件可以定义：

自定义类型。使用自定义类型来构建你的数据模型。
端点。一个服务是一组相关的 REST 端点。
错误。一个错误表示来自端点的失败（非 200）响应。
导入。使用导入在文件间共享类型。

imdb.yml

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:
        - NotFoundError
        - UnauthorizedError
types:
  Movie:
    properties:
      title: string
      rating:
        type: double
        docs: The rating scale from one to five stars
      id:
        type: MovieId
        docs: The unique identifier for a movie
  CreateMovieRequest:
    properties:
      title: string
      rating: double
errors:
  NotFoundError:
    http:
      statusCode: 404
    type:
      properties:
        id: MovieId
  UnauthorizedError:
    http:
      statusCode: 401

为什么需要另一种格式？

Google 构建了 gRPC。Amazon 构建了 Smithy。Facebook 构建了 GraphQL。Palantir 构建了 Conjure。这些公司放弃了 OpenAPI，选择了更简洁的 API Definition Language。

我们构建 Fern 是为了将这种设计产品化，并让所有软件公司都能使用它。

尽管是描述 API 的不同格式，你永远不会被锁定在 Fern 中。 将你的 Fern Definition 转换为 OpenAPI 很容易。