Fern 定义高级

Fern 定义中的示例

使用 Fern 定义添加 API 示例，这些示例会显示在 SDK 注释、API 参考文档和 Postman 集合中。

以 Markdown 格式查看

您可以为类型和端点添加示例。示例会显示为 SDK 中的注释、文档的请求和响应部分，以及 Postman 集合中。

验证

Fern CLI 会验证您的示例是否与预期的类型匹配。以下内容无法编译：

1types:
2  UserId:
3    type: integer
4    examples:
5      - value: hello # 不是整数
CLI 错误消息
$[api]: example.yml -> types -> UserId -> examples[0]
$       期望示例为整数。示例值为："hello"

引用示例

您可以引用来自其他类型、端点或错误的示例。

就像类型一样，您可以组合示例。要引用来自其他类型的示例，请使用 $。

1types:
2  UserId:
3    type: integer
4    examples:
5      - name: Example1
6        value: user-id-123
7
8  User:
9    properties:
10      id: UserId
11      name: string
12    examples:
13      - value:
14          id: $UserId.Example1
15          name: Jane Smith

类型示例

对象

1types:
2  ShipTo:
3    properties:
4      street1: string
5      street2: optional<string>
6      city: string
7      state: string
8      postalCode: string
9      country: Country
10      isResidential: boolean
11    examples:
12      - name: WhiteHouse
13        value:
14          street1: 1600 Pennsylvania Avenue NW
15          city: Washington DC
16          state: Washington DC
17          postalCode: "20500"
18          country: US
19          isResidential: true
20      - name: EmpireStateBuilding
21        value:
22          street1: 350 5th Ave
23          street2: Attn: Maintenance Department
24          city: New York
25          state: NY
26          postalCode: "10118"
27          country: US
28          isResidential: false
生成的 TypeScript SDK
1/**
2 * 代表一个邮寄地址。
3 * 
4 * 白宫地址
5 * @example {
6 *  street1: "1600 Pennsylvania Avenue NW",
7 *  city: "Washington DC",
8 *  state: "Washington DC",
9 *  postalCode: "20500",
10 *  country: "US",
11 *  isResidential: true
12 * }
13 * 
14 * * 帝国大厦地址
15 * @example {
16 *  street1: "350 5th Ave",
17 *  street2: "Attn: Maintenance Department",
18 *  city: "New York",
19 *  state: "NY",
20 *  postalCode: "10118",
21 *  country: "US",
22 *  isResidential: false
23 * }
24 */
25type ShipTo = {
26  street1: string;
27  street2?: string;
28  city: string;
29  state: string;
30  postalCode: string;
31  country: Country;
32  isResidential: boolean;
33};

列表

1 Shipments:
2    type: list<ShipmentStatus>
3    examples:
4      - name: Default
5        value:
6          - status: "InTransit"
7            estimatedDeliveryDate: "2024-01-11"
8          - status: "Delivered"
9            estimatedDeliveryDate: "2024-01-13"

联合

有区分的联合

1types:
2  Animal:
3    union:
4      dog: Dog
5      cat: Cat
6    examples:
7      - value:
8          type: dog
9          likesToWoof: true
10  Dog:
11    properties:
12      likesToWoof: boolean
13  Cat:
14    properties:
15      likesToMeow: boolean
生成的 TypeScript SDK
1/**
2 * 代表一个动物，可以是狗或猫。
3 *
4 * 狗的示例：
5 * @example {
6 *  type: "dog",
7 *  likesToWoof: true
8 * }
9 */
10type Animal = Dog | Cat;

无区分的联合

1types:
2  Animal:
3    discriminated: false
4    union:
5      - Dog
6      - Cat
7    examples:
8      - value:
9          likesToMeow: true
10  Dog:
11    properties:
12      likesToWoof: boolean
13  Cat:
14    properties:
15      likesToMeow: boolean
生成的 TypeScript SDK
1/**
2 * 代表一个动物，可以是狗或猫。
3 *
4 * 动物作为猫的示例：
5 * @example {
6 *  likesToMeow: true
7 * }
8 */
9type Animal = Dog | Cat;

别名

1types:
2  UserId:
3    docs: 用户的唯一标识符
4    type: string
5    examples:
6      - value: user-id-123
生成的 TypeScript SDK
1/** 
2* 用户的唯一标识符 * 
3* @example "user-id-123" 
4*/ 
5type UserId = string;

端点示例

您可以为端点添加成功和错误响应的示例。示例可以引用类型的示例以避免重复。

1service:
2  auth: true
3  base-path: ""
4  endpoints:
5    CreateShippingLabel:
6      docs: 创建新的运输标签。
7      method: POST
8      path: /shipping
9      request: CreateShippingLabelRequest
10      response: ShippingLabel
11      errors:
12        - NotAuthorized
13        - InsufficientFunds
14      examples:
15        # 不引用其他示例的成功响应。
16        - request:
17            orderId: "online_789"
18            weightInOunces: 5
19          response:
20            body:
21              orderId: "online_789"
22              weightInOunces: 5
23              trackingNumber: "1Z26W8370303469306"
24              price: 2.50
25
26        # 使用引用的成功响应。
27        - request: $CreateShippingLabelRequest.SuccessfulRequest
28          response:
29            body: $ShippingLabel.Default
30
31        # 错误响应。
32        - request: $CreateShippingLabelRequest.InsufficientFundsRequest
33          response:
34            error: InsufficientFunds
35            body: $InsufficientFundsBody.Default
36
37types:
38  CreateShippingLabelRequest:
39    properties:
40      orderId: string
41      weightInOunces: integer
42    examples:
43      - name: SuccessfulRequest
44        value:
45          orderId: "online_123"
46          weightInOunces: 13
47      - name: InsufficientFundsRequest
48        value:
49          orderId: "online_456"
50          weightInOunces: 2000
51
52  ShippingLabel:
53    properties:
54      orderId: string
55      weightInOunces: integer
56      trackingNumber: string
57      price: double
58    examples:
59      - name: Default
60        value:
61          orderId: "online_123"
62          weightInOunces: 13
63          trackingNumber: "1Z12345E0205271688"
64          price: 12.35
65
66  InsufficientFundsBody:
67    properties:
68      message: string
69    examples:
70      - name: Default
71        value:
72          message: "Insufficient funds to create shipping label."
73
74errors:
75  NotAuthorized:
76    status-code: 401
77  InsufficientFunds:
78    status-code: 422
79    type: InsufficientFundsBody

带请求头的示例

当您在 api.yml 中定义了全局请求头时，必须在示例中包含它们：

1service:
2  auth: true
3  base-path: ""
4  endpoints:
5    CreateShippingLabel:
6      docs: 创建新的运输标签。
7      method: POST
8      path: /shipping
9      request: CreateShippingLabelRequest
10      response: ShippingLabel
11      errors:
12        - NotAuthorized
13        - InsufficientFunds
14      examples:
15        - headers:
16            X-App-Id: "app_12345"
17          request:
18            orderId: "online_789"
19            weightInOunces: 5
20          response:
21            body:
22              orderId: "online_789"
23              weightInOunces: 5
24              trackingNumber: "1Z26W8370303469306"
25              price: 2.50

路径参数示例

1service:
2  auth: true
3  base-path: ""
4  endpoints:
5    TrackShipment:
6      docs: 跟踪货物的状态。
7      method: GET
8      path: /shipping/{trackingNumber}
9      path-parameters: 
10        trackingNumber: string
11      response: ShipmentStatus
12      examples:
13        - path-parameters: 
14            trackingNumber: "1Z26W8370303469306"
15          response:
16            body:
17              status: "InTransit"
18              estimatedDeliveryDate: "2024-01-11"