跳到导航
OpenAPI扩展

分页

以 Markdown 格式查看
企业功能

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

x-fern-pagination 扩展为 OpenAPI 规范中的列表端点配置自动分页。SDK 和 CLI 用户无需手动管理页面令牌即可获得自动分页功能。

要配置分页：

  1. 使用 x-fern-pagination 扩展注释所需的分页端点
  2. 指定分页方案（offset、cursor、next_uri 或 next_path）
  3. 使用点访问记法指定 results 的位置
paths:
  /plants:
    get:
      operationId: list_plants
      x-fern-pagination:
        offset: $request.page_number
        results: $response.results
      parameters:
        - name: page_number
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of plants
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $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。

MyResponseObject:
  type: object
  properties:
    my_nested_object:
      type: object
      properties:
        inner_list:
          type: array
          items:
            $ref: '#/components/schemas/Plant'