> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiIxZDA1ZTg0MC03NmQ1LTQ0NGMtODE4Ny04Y2E1ZmIyODgwNzUiLCJleHAiOjE3Nzg0OTMxMDEsImlhdCI6MTc3ODQ5MjgwMX0.NC04uqFSb9ke1zkVySWm6aU-j3Fvixej-bDRH9JJgCc
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 分页

> 使用 x-fern-pagination 扩展为列表端点配置自动分页

<Warning title="专业版和企业版功能">
  此功能仅适用于[专业版和企业版计划](https://buildwithfern.com/pricing)。如需开始使用，请联系 [support@buildwithfern.com](mailto:support@buildwithfern.com)。
</Warning>

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

要配置分页：

1. 使用 `x-fern-pagination` 扩展注解所需的分页端点
2. 指定分页方案（`offset`、`cursor`、`next_uri` 或 `next_path`）
3. 使用点访问表示法指定 `results` 的位置

<CodeBlocks>
  ```yaml title="偏移分页" {5-7}
  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'
  ```

  ```yaml title="游标分页" {5-8}
  paths:
    /plants:
      get:
        operationId: list_plants
        x-fern-pagination:
          cursor: $request.cursor
          next_cursor: $response.next
          results: $response.results
        parameters:
          - name: cursor
            in: query
            schema:
              type: string
        responses:
          '200':
            description: List of plants
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    next:
                      type: string
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Plant'
  ```

  ```yaml title="URI 分页" {5-7}
  paths:
    /plants:
      get:
        operationId: list_plants
        x-fern-pagination:
          next_uri: $response.next_page_url
          results: $response.results
        responses:
          '200':
            description: List of plants
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    next_page_url:
                      type: string
                      nullable: true
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Plant'
  ```

  ```yaml title="路径分页" {5-7}
  paths:
    /plants:
      get:
        operationId: list_plants
        x-fern-pagination:
          next_path: $response.next_page_path
          results: $response.results
        responses:
          '200':
            description: List of plants
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    next_page_path:
                      type: string
                      nullable: true
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Plant'
  ```
</CodeBlocks>

## 配置选项

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

<Info title="查找 `results` 的位置">
  如果您的结果嵌套在响应对象中，请使用点访问表示法指定路径。例如，如果结果位于 `my_nested_object.inner_list` 中，`results` 路径将是 `$response.my_nested_object.inner_list`。

  ```yaml {4, 7}
  MyResponseObject:
    type: object
    properties:
      my_nested_object:
        type: object
        properties:
          inner_list:
            type: array
            items:
              $ref: '#/components/schemas/Plant'
  ```
</Info>