Fern 定义端点

Fern Definition 中的端点

以 Markdown 格式查看

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

服务定义

每个服务定义：

  1. base-path（基础路径）：所有端点 HTTP 路径的通用前缀
  2. 服务是否需要身份验证
  3. Endpoints（端点）
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 方法
  • 请求信息 （可选）
    • Query-parameters（查询参数）
    • Headers（请求头）
    • Request body（请求体）
  • 成功（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: 地址的唯一标识符。
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