Fern 定义端点

Fern 定义中的端点

以 Markdown 格式查看

在 Fern 中，您可以将相关的端点组织到一个服务中。这种分组方式提高了清晰度，使生成的 SDK 更加符合习惯。

服务定义

每个服务定义：

  1. 一个基础路径：所有端点 HTTP 路径的共同前缀
  2. 服务是否需要身份验证
  3. 端点
user.yml
1  service: 
2    base-path: /users # 这定义了方法的组/命名空间
3    auth: false 
4    endpoints: {}

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

章节显示名称

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

SDK 方法名称

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

例如，给定以下定义：

users.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    create:
6      path: ""
7      method: POST
8      request: CreateUserRequest

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

端点

端点包括：

  • 一个 URL 路径 （可选择性地包括路径参数）
  • 一个显示名称 （可选）
  • 一个 HTTP 方法
  • 请求信息 （可选）
    • 查询参数
    • 标头
    • 请求体
  • 成功（200）响应信息 （可选）
  • 此端点可能返回的错误（非 200）响应 （可选）

URL 路径

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

user.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    getAllUsers:
6      path: /all
7      method: GET

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

  • 环境 URL
  • 服务 base-path
  • 端点 path

端点显示名称

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

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

user.yml
1service:
2  base-path: /v3
3  auth: false
4  endpoints:
5    addPlant:
6      path: /plant
7      display-name: Add a new plant to the store
8      method: POST

路径参数

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

user.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    getUser:
6      path: /{userId} 
7      path-parameters: 
8        userId: string
9      method: GET

服务也可以有路径参数：

project.yml
1service: 
2  base-path: /projects/{projectId}
3  path-parameters: 
4    projectId: string 
5  auth: false 
6  endpoints: 
7    ...

查询参数

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

user.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    getAllUsers:
6      path: /all
7      method: GET
8      request:
9        # 符合习惯的 SDK 需要这个名称
10        name: GetAllUsersRequest
11        query-parameters:
12          limit: optional<integer>

allow-multiple

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

user.yml
1  ...
2  query-parameters:
3    filter:
4      type: string
5      allow-multiple: true

身份验证

每个端点可以覆盖服务中指定的身份验证行为。

user.yml
1service: 
2  base-path: /users 
3  auth: false 
4  endpoints: 
5    getMe: 
6      path: "" 
7      method: GET 
8      # 这个端点将进行身份验证
9      auth: true 
10      docs: 根据 Authorization 标头返回当前用户。

标头

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

user.yml
1service: 
2  base-path: /users 
3  auth: false 
4  endpoints: 
5    getAllUsers: 
6      path: /all
7      method: GET 
8      request: 
9        # 符合习惯的 SDK 需要这个名称
10        name: GetAllUsersRequest 
11        headers: 
12          X-Endpoint-Header: string

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

user.yml
1service: 
2  base-path: /users 
3  auth: false 
4  headers: 
5    X-Service-Header: string 
6  endpoints: 
7    getAllUsers: 
8      path: /all 
9      method: GET 
10      request: 
11        # 符合习惯的 SDK 需要这个名称
12        name: GetAllUsersRequest 
13        headers: 
14          X-Endpoint-Header: string

请求体

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

user.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    setUserName:
6      path: /{userId}/set-name
7      path-parameters:
8        userId: string
9      method: POST
10      request: string

内联请求体

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

user.yml
1service: 
2  base-path: /users 
3  auth: false 
4  endpoints: 
5    createUser: 
6      path: /create 
7      method: POST 
8      request: 
9        # 符合习惯的 SDK 需要这个名称
10        name: CreateUserRequest 
11        body: 
12          properties: 
13            userName: string

成功响应

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

user.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    getAllUsers:
6      path: /all
7      method: GET
8      response: list<User>
9
10types:
11  User:
12    properties:
13      userId: string
14      name: string

响应状态码

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

user.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    create: :
6      path: ""
7      method: POST
8      request: CreateUserRequest
9      response: 
10        type: User
11        status-code: 201
12
13types:
14  User:
15    properties:
16      userId: string
17      name: string

分页

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

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

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

1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    list:
6      path: ""
7      method: GET
8      pagination:
9        offset: $request.page
10        step: $request.page_size # 推荐
11        results: $response.data
12        has-next-page: $response.has_more
13      request:
14        name: ListUsersRequest
15        query-parameters:
16          page: optional<integer>
17          page_size: optional<integer>
18      response: ListUsersResponse
19
20types:
21  ListUsersResponse:
22    properties:
23      data: list<User>
24      has_more: boolean

pagination 字段支持以下属性：

PropertyDescription
offsetPath to the offset parameter in the request (e.g., $request.page)
cursorPath to the cursor parameter in the request (e.g., $request.cursor)
next_cursorPath to the next cursor value in the response (required for cursor pagination)
next_uriPath to the next page’s URL in the response (e.g., $response.next_page_url)
next_pathPath to the relative path for the next page in the response (e.g., $response.next_page_path)
resultsPath to the results array in the response (e.g., $response.data)
stepPath to the page size parameter, ensures offset increments correctly
has-next-pagePath to a boolean indicator for additional pages

幂等端点

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

service.yml
1service:
2  base-path: /transactions
3  auth: true
4  endpoints:
5    send:
6      path: ""
7      method: POST
8      idempotent: true
9      request: SendTransactionRequest
10      response: Transaction

错误响应

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

user.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    getUser:
6      path: /{userId}
7      path-parameters:
8        userId: string
9      method: GET
10      response: User
11      errors:
12        - UserNotFoundError
13
14types:
15  User:
16    properties:
17      userId: string
18      name: string
19
20errors:
21  UserNotFoundError:
22    status-code: 404

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

指定示例

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

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

user.yml
1service:
2  base-path: /users
3  auth: false
4  endpoints:
5    getUser:
6      path: /{userId}
7      path-parameters:
8        userId: string
9      method: GET
10      response: User
11      errors:
12        - UserNotFoundError
13      examples:
14        - path-parameters:
15            userId: alice-user-id
16          response:
17            body:
18              userId: alice-user-id
19              name: Alice
20
21types:
22  User:
23    properties:
24      userId: string
25      name: string
26
27errors:
28  UserNotFoundError:
29    status-code: 404

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

1service:
2  auth: true
3  base-path: /address
4  endpoints:
5    create:
6      method: POST
7      path: ""
8      request: CreateAddress
9      response: Address
10      examples:
11        - request: $CreateAddress.WhiteHouse
12          response:
13            body: $Address.WhiteHouseWithID
14
15  CreateAddress:
16    properties:
17      street1: string
18      street2: optional<string>
19      city: string
20      state: string
21      postalCode: string
22      country: string
23      isResidential: boolean
24    examples:
25      - name: WhiteHouse
26        value:
27          street1: 1600 Pennsylvania Avenue NW
28          city: Washington DC
29          state: Washington DC
30          postalCode: "20500"
31          country: US
32          isResidential: true
33
34  Address:
35    extends: CreateAddress
36    properties:
37      id:
38        type: uuid
39        docs: The unique identifier for the address.
40    examples:
41      - name: WhiteHouseWithID
42        value:
43          id: 65ce514c-41e3-11ee-be56-0242ac120002
44          street1: 1600 Pennsylvania Avenue NW
45          city: Washington DC
46          state: Washington DC
47          postalCode: "20500"
48          country: US
49          isResidential: true

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

user.yml
1examples: 
2  - path-parameters: 
3      userId: some-user-id 
4    query-parameters:
5      limit: 50 
6    headers: 
7      X-My-Header: some-value 
8    response: 
9      body: 
10        response-field: hello

失败示例

您也可以指定失败的端点调用示例。向响应示例添加 error 属性来指定您正在演示的失败。

user.yml
1examples:
2  - path-parameters:
3      userId: missing-user-id
4    response:
5      error: UserNotFoundError
6
7errors:
8  UserNotFoundError:
9    status-code: 404

如果错误有体，那么您必须在示例中包含该体。

user.yml
1examples:
2  - path-parameters:
3      userId: missing-user-id
4    response:
5      error: UserNotFoundError
6      body: "User with id `missing-user-id` was not found"
7
8errors:
9  UserNotFoundError:
10    status-code: 404
11    type: string

从类型引用示例

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

user.yml
1service:
2  base-path: /users
3  auth: true
4  endpoints:
5    getUser:
6      method: GET
7      path: /{userId}
8      path-parameters:
9        userId: UserId
10      examples:
11        - path-parameters:
12            userId: $UserId.Example1
13
14types:
15  UserId:
16  type: integer
17  examples: 
18    - name: Example1
19      value: user-id-123