OpenAPI扩展

分页

以 Markdown 格式查看
专业版和企业版功能

此功能仅适用于专业版和企业版计划。如需开始使用，请联系 support@buildwithfern.com。

x-fern-pagination 扩展为 OpenAPI 规范中的列表端点配置自动分页。Fern 生成的 SDK 提供简单的迭代器，可以自动处理分页，因此 SDK 用户可以遍历所有结果，而无需手动管理分页复杂性。

要配置分页：

  1. 使用 x-fern-pagination 扩展注解所需的分页端点
  2. 指定分页方案（offset、cursor、next_uri 或 next_path）
  3. 使用点访问表示法指定 results 的位置
1paths:
2  /plants:
3    get:
4      operationId: list_plants
5      x-fern-pagination:
6        offset: $request.page_number
7        results: $response.results
8      parameters:
9        - name: page_number
10          in: query
11          schema:
12            type: integer
13      responses:
14        '200':
15          description: List of plants
16          content:
17            application/json:
18              schema:
19                type: object
20                properties:
21                  results:
22                    type: array
23                    items:
24                      $ref: '#/components/schemas/Plant'

配置选项

x-fern-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

查找 results 的位置

如果您的结果嵌套在响应对象中，请使用点访问表示法指定路径。例如，如果结果位于 my_nested_object.inner_list 中，results 路径将是 $response.my_nested_object.inner_list。

1MyResponseObject:
2  type: object
3  properties:
4    my_nested_object:
5      type: object
6      properties:
7        inner_list:
8          type: array
9          items:
10            $ref: '#/components/schemas/Plant'