For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
预约演示登录免费开始
  • 概览
    • 什么是 API 定义？
    • 项目结构
      • 概览
      • 身份验证
      • 类型
        • Webhooks
        • WebSockets
        • 导入
        • 示例
        • 受众
        • 可用性
        • Availability
Checking status...
SOC2Soc 2 Type II
© 2026 Fern • Birch Solutions, Inc., a Postman company

Documentation

SDKsDocsAsk FernCLI Reference

API Definitions

OpenAPIAsyncAPIOpenRPCgRPC

Resources

BlogSupportPricing

Company

Brand KitPrivacy PolicyTerms of Service
LogoLogo
预约演示登录免费开始
在本页
  • 验证
  • 引用示例
  • 类型示例
  • 对象
  • 列表
  • 联合类型
  • 可区分联合
  • 不可区分联合
  • 别名
  • 端点示例
  • 包含请求头的示例
  • 路径参数示例
Fern 定义高级

Fern Definition 中的示例

使用 Fern Definition 添加 API 示例，这些示例将显示在 SDK 的注释、API 参考文档以及 Postman 集合中。

||以 Markdown 格式查看|
此页面是否有帮助？
在仪表板中编辑
上一个

Fern 定义中的导入

下一个

Fern 定义中的受众

您可以为类型和端点添加示例。示例会显示在您的 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 * Represents a shipping address.
3 * 
4 * The White House address
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 * * The Empire State Building address
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 * Represents an animal, which can be either a Dog or a Cat.
3 *
4 * Example of a Dog:
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 * Represents an Animal, which can be either a Dog or a Cat.
3 *
4 * Example of an Animal as a Cat:
5 * @example {
6 *  likesToMeow: true
7 * }
8 */
9type Animal = Dog | Cat;

别名

1types:
2  UserId:
3    docs: A unique identifier for a user
4    type: string
5    examples:
6      - value: user-id-123
生成的 TypeScript SDK
1/** 
2* A unique identifier for a user * 
3* @example "user-id-123" 
4*/ 
5type UserId = string;

端点示例

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

1service:
2  auth: true
3  base-path: ""
4  endpoints:
5    CreateShippingLabel:
6      docs: Create a new shipping label.
7      method: POST
8      path: /shipping
9      request: CreateShippingLabelRequest
10      response: ShippingLabel
11      errors:
12        - NotAuthorized
13        - InsufficientFunds
14      examples:
15        # A successful response that doesn't reference other examples.
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        # A successful response that uses references.
27        - request: $CreateShippingLabelRequest.SuccessfulRequest
28          response:
29            body: $ShippingLabel.Default
30
31        # An error response.
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: Create a new shipping label.
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: Track the status of a shipment.
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"