Fern Definition 中的端点 | Fern Documentation

在 Fern 中，您将相关端点组织成一个 Service（服务）。这种分组提高了清晰度，并使生成的 SDK 更加地道。

服务定义

每个服务定义：

base-path（基础路径）：所有端点 HTTP 路径的通用前缀
服务是否需要身份验证
Endpoints（端点）

user.yml

  service: 
    base-path: /users # 这定义了方法的组/命名空间
    auth: false 
    endpoints: {}

要定义具有空基础路径的服务，请使用空字符串：base-path: ""

节显示名称

默认情况下，API 参考中的节名称来自服务文件名（例如，user.yml 变成”User”）。要覆盖节的显示名称，在您的 docs.yml 中使用 section 属性。

SDK 方法名称

SDK 方法名称直接从服务文件名和端点键派生。文件名成为命名空间，端点键成为方法名。

例如，给定以下定义：

users.yml

service:
  base-path: /users
  auth: false
  endpoints:
    create:
      path: ""
      method: POST
      request: CreateUserRequest

Fern 生成一个名为 client.users.create() 的方法。

端点

端点包括：

URL 路径 （可选择包含路径参数）
显示名称 （可选）
HTTP 方法
请求信息 （可选）
- Query-parameters（查询参数）
- Headers（请求头）
- Request body（请求体）
成功（200）响应信息 （可选）
此端点可能返回的错误（非 200）响应 （可选）

URL 路径

每个端点都有一个 URL 路径。

user.yml

service:
  base-path: /users
  auth: false
  endpoints:
    getAllUsers:
      path: /all
      method: GET

端点的完整路径是以下内容的连接：

环境 URL
服务 base-path
端点 path

端点显示名称

显示名称将作为端点的标题出现。默认情况下，显示名称等于端点名称的”标题大小写”。如果您想要自定义端点名称，可以设置显示名称。

在下面的示例中，“Add a new plant to the store” 作为 API 参考中端点页面的标题显示。

user.yml

service:
  base-path: /v3
  auth: false
  endpoints:
    addPlant:
      path: /plant
      display-name: Add a new plant to the store
      method: POST

路径参数

为您的端点提供路径参数以创建动态 URL。

user.yml

service:
  base-path: /users
  auth: false
  endpoints:
    getUser:
      path: /{userId} 
      path-parameters: 
        userId: string
      method: GET

服务也可以有路径参数：

project.yml

service: 
  base-path: /projects/{projectId}
  path-parameters: 
    projectId: string 
  auth: false 
  endpoints: 
    ...

查询参数

每个端点可以指定查询参数：

user.yml

service:
  base-path: /users
  auth: false
  endpoints:
    getAllUsers:
      path: /all
      method: GET
      request:
        # 这个名称对于地道的 SDK 是必需的
        name: GetAllUsersRequest
        query-parameters:
          limit: optional<integer>

`allow-multiple`

使用 allow-multiple 指定查询参数在 URL 中允许多次出现，如 ?filter=jane&filter=smith。这将改变生成的 SDK，使消费者可以为查询参数提供多个值。

user.yml

  ...
  query-parameters:
    filter:
      type: string
      allow-multiple: true

认证

每个端点都可以覆盖服务中指定的认证行为。

user.yml

service: 
  base-path: /users 
  auth: false 
  endpoints: 
    getMe: 
      path: "" 
      method: GET 
      # 此端点将进行认证
      auth: true 
      docs: 基于 Authorization 头返回当前用户。

请求头

每个端点可以指定请求头：

user.yml

service: 
  base-path: /users 
  auth: false 
  endpoints: 
    getAllUsers: 
      path: /all
      method: GET 
      request: 
        # 这个名称对于地道的 SDK 是必需的
        name: GetAllUsersRequest 
        headers: 
          X-Endpoint-Header: string

服务也可以指定请求头。这些头将级联到服务的端点。

user.yml

service: 
  base-path: /users 
  auth: false 
  headers: 
    X-Service-Header: string 
  endpoints: 
    getAllUsers: 
      path: /all 
      method: GET 
      request: 
        # 这个名称对于地道的 SDK 是必需的
        name: GetAllUsersRequest 
        headers: 
          X-Endpoint-Header: string

请求体

端点可以指定请求体类型。

user.yml

service:
  base-path: /users
  auth: false
  endpoints:
    setUserName:
      path: /{userId}/set-name
      path-parameters:
        userId: string
      method: POST
      request: string

内联请求体

如果请求体是一个对象，您可以内联类型声明。这使生成的 SDK 更加地道。

user.yml

service: 
  base-path: /users 
  auth: false 
  endpoints: 
    createUser: 
      path: /create 
      method: POST 
      request: 
        # 这个名称对于地道的 SDK 是必需的
        name: CreateUserRequest 
        body: 
          properties: 
            userName: string

成功响应

端点可以指定 response，这是在成功（200）调用时返回的主体类型。

user.yml

service:
  base-path: /users
  auth: false
  endpoints:
    getAllUsers:
      path: /all
      method: GET
      response: list<User>
types:
  User:
    properties:
      userId: string
      name: string

响应状态码

您还可以使用 status-code 字段为成功响应指定自定义状态码。

user.yml

service:
  base-path: /users
  auth: false
  endpoints:
    create: :
      path: ""
      method: POST
      request: CreateUserRequest
      response: 
        type: User
        status-code: 201
types:
  User:
    properties:
      userId: string
      name: string

分页

Fern 支持偏移、游标、URI 和基于路径的分页方案。要在生成的 SDK 中设置自动分页：

使用 pagination 字段标注所需的分页端点
指定分页方案（offset、cursor、next_uri 或 next_path）
使用点访问表示法指定 results 的位置。

偏移分页选项

在大多数偏移分页配置中包含 step，以确保偏移按页面大小递增。当您的 API 返回附加页面的布尔指示器时，请使用 has-next-page。

service:
  base-path: /users
  auth: false
  endpoints:
    list:
      path: ""
      method: GET
      pagination:
        offset: $request.page
        step: $request.page_size # 推荐
        results: $response.data
        has-next-page: $response.has_more
      request:
        name: ListUsersRequest
        query-parameters:
          page: optional<integer>
          page_size: optional<integer>
      response: ListUsersResponse
types:
  ListUsersResponse:
    properties:
      data: list<User>
      has_more: boolean

pagination 字段支持以下属性：

Property	Description
`offset`	Path to the offset parameter in the request (e.g., `$request.page`)
`cursor`	Path to the cursor parameter in the request (e.g., `$request.cursor`)
`next_cursor`	Path to the next cursor value in the response (required for cursor pagination)
`next_uri`	Path to the next page’s URL in the response (e.g., `$response.next_page_url`)
`next_path`	Path to the relative path for the next page in the response (e.g., `$response.next_page_path`)
`results`	Path to the results array in the response (e.g., `$response.data`)
`step`	Path to the page size parameter, ensures offset increments correctly
`has-next-page`	Path to a boolean indicator for additional pages

幂等端点

将端点标记为幂等，以允许 SDK 用户为安全请求重试指定幂等性头。您还必须在 api.yml 中配置幂等性头来定义哪些头可用。

service.yml

service:
  base-path: /transactions
  auth: true
  endpoints:
    send:
      path: ""
      method: POST
      idempotent: true
      request: SendTransactionRequest
      response: Transaction

错误响应

端点可以指定错误响应，详细说明端点可能返回的非 200 响应。

user.yml

service:
  base-path: /users
  auth: false
  endpoints:
    getUser:
      path: /{userId}
      path-parameters:
        userId: string
      method: GET
      response: User
      errors:
        - UserNotFoundError
types:
  User:
    properties:
      userId: string
      name: string
errors:
  UserNotFoundError:
    status-code: 404

您可以在错误页面了解更多关于如何定义错误的信息。

指定示例

当您声明一个示例时，您还可以指定一些该端点如何使用的示例。这些被编译器用来增强生成的输出。示例将在您的 SDK、API 文档和 Postman 集合中显示为注释。

您可以为端点、类型和错误添加示例。

user.yml

service:
  base-path: /users
  auth: false
  endpoints:
    getUser:
      path: /{userId}
      path-parameters:
        userId: string
      method: GET
      response: User
      errors:
        - UserNotFoundError
      examples:
        - path-parameters:
            userId: alice-user-id
          response:
            body:
              userId: alice-user-id
              name: Alice
types:
  User:
    properties:
      userId: string
      name: string
errors:
  UserNotFoundError:
    status-code: 404

如果您要向端点添加示例且类型已经有示例，您可以使用 $ 引用它。

service:
  auth: true
  base-path: /address
  endpoints:
    create:
      method: POST
      path: ""
      request: CreateAddress
      response: Address
      examples:
        - request: $CreateAddress.WhiteHouse
          response:
            body: $Address.WhiteHouseWithID
  CreateAddress:
    properties:
      street1: string
      street2: optional<string>
      city: string
      state: string
      postalCode: string
      country: string
      isResidential: boolean
    examples:
      - name: WhiteHouse
        value:
          street1: 1600 Pennsylvania Avenue NW
          city: Washington DC
          state: Washington DC
          postalCode: "20500"
          country: US
          isResidential: true
  Address:
    extends: CreateAddress
    properties:
      id:
        type: uuid
        docs: 地址的唯一标识符。
    examples:
      - name: WhiteHouseWithID
        value:
          id: 65ce514c-41e3-11ee-be56-0242ac120002
          street1: 1600 Pennsylvania Avenue NW
          city: Washington DC
          state: Washington DC
          postalCode: "20500"
          country: US
          isResidential: true

示例包含有关端点调用的所有信息，包括请求体、路径参数、查询参数、头和响应体。

user.yml

examples: 
  - path-parameters: 
      userId: some-user-id 
    query-parameters:
      limit: 50 
    headers: 
      X-My-Header: some-value 
    response: 
      body: 
        response-field: hello

失败示例

您还可以指定失败端点调用的示例。添加 error 属性到响应示例以指定您正在演示哪个失败。

user.yml

examples:
  - path-parameters:
      userId: missing-user-id
    response:
      error: UserNotFoundError
errors:
  UserNotFoundError:
    status-code: 404

如果错误有主体，则必须在示例中包含主体。

user.yml

examples:
  - path-parameters:
      userId: missing-user-id
    response:
      error: UserNotFoundError
      body: "User with id `missing-user-id` was not found"
errors:
  UserNotFoundError:
    status-code: 404
    type: string

从类型引用示例

为避免重复，您可以使用 $ 从类型引用示例。

user.yml

service:
  base-path: /users
  auth: true
  endpoints:
    getUser:
      method: GET
      path: /{userId}
      path-parameters:
        userId: UserId
      examples:
        - path-parameters:
            userId: $UserId.Example1
types:
  UserId:
  type: integer
  examples: 
    - name: Example1
      value: user-id-123