跳到导航
Fern 定义高级

Fern Definition 中的示例

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

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

验证

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

types:
  UserId:
    type: integer
    examples:
      - value: hello # 不是整数
CLI 错误信息
[api]: example.yml -> types -> UserId -> examples[0]
       预期示例为整数类型。示例值为: "hello"

引用示例

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

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

types:
  UserId:
    type: integer
    examples:
      - name: Example1
        value: user-id-123
  User:
    properties:
      id: UserId
      name: string
    examples:
      - value:
          id: $UserId.Example1
          name: Jane Smith

类型示例

对象

types:
  ShipTo:
    properties:
      street1: string
      street2: optional<string>
      city: string
      state: string
      postalCode: string
      country: Country
      isResidential: boolean
    examples:
      - name: WhiteHouse
        value:
          street1: 1600 Pennsylvania Avenue NW
          city: Washington DC
          state: Washington DC
          postalCode: "20500"
          country: US
          isResidential: true
      - name: EmpireStateBuilding
        value:
          street1: 350 5th Ave
          street2: Attn: Maintenance Department
          city: New York
          state: NY
          postalCode: "10118"
          country: US
          isResidential: false
生成的 TypeScript SDK
/**
 * Represents a shipping address.
 * 
 * The White House address
 * @example {
 *  street1: "1600 Pennsylvania Avenue NW",
 *  city: "Washington DC",
 *  state: "Washington DC",
 *  postalCode: "20500",
 *  country: "US",
 *  isResidential: true
 * }
 * 
 * * The Empire State Building address
 * @example {
 *  street1: "350 5th Ave",
 *  street2: "Attn: Maintenance Department",
 *  city: "New York",
 *  state: "NY",
 *  postalCode: "10118",
 *  country: "US",
 *  isResidential: false
 * }
 */
type ShipTo = {
  street1: string;
  street2?: string;
  city: string;
  state: string;
  postalCode: string;
  country: Country;
  isResidential: boolean;
};

列表

 Shipments:
    type: list<ShipmentStatus>
    examples:
      - name: Default
        value:
          - status: "InTransit"
            estimatedDeliveryDate: "2024-01-11"
          - status: "Delivered"
            estimatedDeliveryDate: "2024-01-13"

联合类型

可区分联合

types:
  Animal:
    union:
      dog: Dog
      cat: Cat
    examples:
      - value:
          type: dog
          likesToWoof: true
  Dog:
    properties:
      likesToWoof: boolean
  Cat:
    properties:
      likesToMeow: boolean
生成的 TypeScript SDK
/**
 * Represents an animal, which can be either a Dog or a Cat.
 *
 * Example of a Dog:
 * @example {
 *  type: "dog",
 *  likesToWoof: true
 * }
 */
type Animal = Dog | Cat;

不可区分联合

types:
  Animal:
    discriminated: false
    union:
      - Dog
      - Cat
    examples:
      - value:
          likesToMeow: true
  Dog:
    properties:
      likesToWoof: boolean
  Cat:
    properties:
      likesToMeow: boolean
生成的 TypeScript SDK
/**
 * Represents an Animal, which can be either a Dog or a Cat.
 *
 * Example of an Animal as a Cat:
 * @example {
 *  likesToMeow: true
 * }
 */
type Animal = Dog | Cat;

别名

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

端点示例

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

service:
  auth: true
  base-path: ""
  endpoints:
    CreateShippingLabel:
      docs: Create a new shipping label.
      method: POST
      path: /shipping
      request: CreateShippingLabelRequest
      response: ShippingLabel
      errors:
        - NotAuthorized
        - InsufficientFunds
      examples:
        # A successful response that doesn't reference other examples.
        - request:
            orderId: "online_789"
            weightInOunces: 5
          response:
            body:
              orderId: "online_789"
              weightInOunces: 5
              trackingNumber: "1Z26W8370303469306"
              price: 2.50
        # A successful response that uses references.
        - request: $CreateShippingLabelRequest.SuccessfulRequest
          response:
            body: $ShippingLabel.Default
        # An error response.
        - request: $CreateShippingLabelRequest.InsufficientFundsRequest
          response:
            error: InsufficientFunds
            body: $InsufficientFundsBody.Default
types:
  CreateShippingLabelRequest:
    properties:
      orderId: string
      weightInOunces: integer
    examples:
      - name: SuccessfulRequest
        value:
          orderId: "online_123"
          weightInOunces: 13
      - name: InsufficientFundsRequest
        value:
          orderId: "online_456"
          weightInOunces: 2000
  ShippingLabel:
    properties:
      orderId: string
      weightInOunces: integer
      trackingNumber: string
      price: double
    examples:
      - name: Default
        value:
          orderId: "online_123"
          weightInOunces: 13
          trackingNumber: "1Z12345E0205271688"
          price: 12.35
  InsufficientFundsBody:
    properties:
      message: string
    examples:
      - name: Default
        value:
          message: "Insufficient funds to create shipping label."
errors:
  NotAuthorized:
    status-code: 401
  InsufficientFunds:
    status-code: 422
    type: InsufficientFundsBody

包含请求头的示例

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

service:
  auth: true
  base-path: ""
  endpoints:
    CreateShippingLabel:
      docs: Create a new shipping label.
      method: POST
      path: /shipping
      request: CreateShippingLabelRequest
      response: ShippingLabel
      errors:
        - NotAuthorized
        - InsufficientFunds
      examples:
        - headers:
            X-App-Id: "app_12345"
          request:
            orderId: "online_789"
            weightInOunces: 5
          response:
            body:
              orderId: "online_789"
              weightInOunces: 5
              trackingNumber: "1Z26W8370303469306"
              price: 2.50

路径参数示例

service:
  auth: true
  base-path: ""
  endpoints:
    TrackShipment:
      docs: Track the status of a shipment.
      method: GET
      path: /shipping/{trackingNumber}
      path-parameters: 
        trackingNumber: string
      response: ShipmentStatus
      examples:
        - path-parameters: 
            trackingNumber: "1Z26W8370303469306"
          response:
            body:
              status: "InTransit"
              estimatedDeliveryDate: "2024-01-11"