> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI3OWNhMGU1Mi1mNDkwLTQ0Y2EtOGQ1Mi1iNjliZmYzMzY3ZmUiLCJleHAiOjE3NzgzODM2OTcsImlhdCI6MTc3ODM4MzM5N30.OsI0l8HjVwEJhJL_oERavZUVigt23pUUeBpvZkOB4ws
>
> 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.

# 配置自动分页

> 通过偏移量、游标、URI 和路径分页方案来分页遍历 API 响应。

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

Fern 的自动分页支持偏移量、游标、URI 和基于路径的分页方案，为 SDK 用户提供简单的迭代器来遍历所有结果，而无需手动管理分页复杂性。

## 生成的 SDK 行为

<Tabs>
  <Tab title="TypeScript" language="typescript">
    一旦为端点配置了分页，Fern 会生成一个返回 `Page<T>` 的 TypeScript SDK 方法，其中 `T` 是底层数据类型。`Page<T>` 实现了 `AsyncIterable` 接口，允许您的用户在 `for await` 循环中使用它。

    ```typescript
    const response = await client.users.list();
    for await (const user of response) {
      console.log(user);
    }
    ```
  </Tab>

  <Tab title="Python" language="python">
    一旦为端点配置了分页，Fern 会生成一个返回 `Pager[T]` 的 Python SDK 方法，其中 `T` 是底层数据类型。`Pager[T]` 实现了 `Generator` 接口，允许您的用户在 `for ... in` 循环中使用它。

    ```python
    for user in client.users.list(page=1, page_size=10):
      print(user)
    ```

    或者使用异步客户端：

    ```python
    async for user in await client.users.list(page=1, page_size=10):
      print(user)
    ```
  </Tab>
</Tabs>

## 设置自动分页

定义您的分页方案并指定结果的位置：

<Tabs>
  <Tab title="OpenAPI">
    <CodeBlocks>
      ```yaml Offset {4-6}
      ...
      paths:
        /plants:
          x-fern-pagination:
            offset: $request.page_number
            results: $response.results
      ...
      ```

      ```yaml Cursor {5-8}
      ...
      paths:
        /plants:
          get:
            x-fern-pagination:
              cursor: $request.cursor
              next_cursor: $response.next
              results: $response.results
      ...
      ```

      ```yaml URI {5-7}
      ...
      paths:
        /plants:
          get:
            x-fern-pagination:
              next_uri: $response.next_page_url
              results: $response.results
      ...
      ```

      ```yaml Path {5-7}
      ...
      paths:
        /plants:
          get:
            x-fern-pagination:
              next_path: $response.next_page_path
              results: $response.results
      ...
      ```
    </CodeBlocks>
  </Tab>

  <Tab title="Fern Definition">
    <CodeBlocks>
      ```yaml Offset {6-8}
      service:
        endpoints:
          listWithOffsetPagination:
            pagination:
              offset: $request.page
              results: $response.data
              step: $request.page_size
              has-next-page: $response.has_more
      ```

      ```yaml Cursor {7}
      service:
        endpoints:
          listWithCursorPagination:
            pagination:
              cursor: $request.starting_after
              next_cursor: $response.page.next.starting_after
              results: $response.data
      ```

      ```yaml URI {5-6}
      service:
        endpoints:
          listWithUriPagination:
            pagination:
              next_uri: $response.next_page_url
              results: $response.data
      ```

      ```yaml Path {5-6}
      service:
        endpoints:
          listWithPathPagination:
            pagination:
              next_path: $response.next_page_path
              results: $response.data
      ```
    </CodeBlocks>
  </Tab>
</Tabs>

有关完整配置详情，请参阅您的 API 定义格式的文档：

<CardGroup cols={2}>
  <Card title="OpenAPI" href="/learn/api-definitions/openapi/extensions/pagination">
    使用 `x-fern-pagination` 扩展注解端点并配置其他属性。
  </Card>

  <Card title="Fern Definition" href="/learn/api-definitions/ferndef/endpoints/overview#pagination">
    使用 `pagination` 字段注解端点并配置其他属性。
  </Card>
</CardGroup>