什么是 Fern Definition？

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

Fern Definition 结构

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

1 npm install -g fern-api
2 fern init

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

fern

fern.config.json# 根级配置

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

definition

api.yml# API 级配置

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

Definition 文件

每个 Fern Definition 文件可以定义：

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

imdb.yml

1 service:
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 
22 types:
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 
38 errors:
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 很容易。

Fern Definition 结构

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

1 npm install -g fern-api
2 fern init

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

fern

fern.config.json# 根级配置

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

definition

api.yml# API 级配置

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

Definition 文件

每个 Fern Definition 文件可以定义：

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

imdb.yml

1 service:
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 
22 types:
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 
38 errors:
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 很容易。

1	service:
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
22	types:
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
38	errors:
39	NotFoundError:
40	http:
41	statusCode: 404
42	type:
43	properties:
44	id: MovieId
45
46	UnauthorizedError:
47	http:
48	statusCode: 401