Fern 定义

什么是 Fern Definition？

以 Markdown 格式查看

Fern Definition 是一组 YAML 文件，是您 API 的单一真实数据源。您可以将 Fern Definition 提交到您的代码库中，其中描述了您的 API 请求、响应、模型、路径、方法、错误和身份验证方案。

想要使用 OpenAPI？没问题，我们同样支持

Fern Definition 结构

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

1npm install -g fern-api
2fern init

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

fern
fern.config.json# 根级配置
generators.yml# 您正在使用的生成器
definition
api.yml# API 级配置
imdb.yml# 端点、类型和错误

Definition 文件

每个 Fern Definition 文件可以定义：

  • 自定义类型。使用自定义类型来构建您的数据模型。
  • 端点。一个服务是一组相关的 REST 端点。
  • 错误。一个错误代表端点的失败（非 200）响应。
  • 导入。使用导入在文件之间共享类型。
imdb.yml
1service:
2  auth: false
3  base-path: /movies
4  endpoints:
5    createMovie:
6      docs: Add a movie to the database
7      method: POST
8      path: /create-movie
9      request: CreateMovieRequest
10      response: MovieId
11
12    getMovie:
13      method: GET
14      path: /{movieId}
15      path-parameters:
16        movieId: MovieId
17      response: Movie
18      errors:
19        - NotFoundError
20        - UnauthorizedError
21
22types:
23  Movie:
24    properties:
25      title: string
26      rating:
27        type: double
28        docs: The rating scale from one to five stars
29      id:
30        type: MovieId
31        docs: The unique identifier for a movie
32
33  CreateMovieRequest:
34    properties:
35      title: string
36      rating: double
37
38errors:
39  NotFoundError:
40    http:
41      statusCode: 404
42    type:
43      properties:
44        id: MovieId
45
46  UnauthorizedError:
47    http:
48      statusCode: 401

为什么要使用另一种格式？

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

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

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