> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/api-references/guides/openapi-layouts.md).

# OpenAPI 布局

当你插入一个 **OpenAPI 参考**，GitBook 可以通过两种方式组织操作。

选择与您希望人们浏览您的 API 方式相匹配的布局。

### 访问此设置

要选择布局：

1. 在您的部分中，点击 **新增...** → **OpenAPI 参考**。你也可以编辑现有的 OpenAPI 参考。
2. 选择你的 OpenAPI 规范。
3. 在 **页面结构**，选择 **每个标签一页** 或 **每个操作一页**.

有关完整设置流程，请参见 [在你的文档中插入 API 参考](/docs/documentation/zh/api-references/openapi/insert-api-reference-in-your-docs.md).

### 可用布局

GitBook 支持两种布局：

* **每个标签一页** 为每个标签创建一个页面。每个页面列出该标签下的所有操作。
* **每个操作一页** 为每个操作创建一个页面。GitBook 会在目录中按标签对这些页面分组。

### 示例输入

这两种布局都基于相同的 OpenAPI 数据：

{% code title="openapi.yaml" %}

```yaml
paths:
  /users:
    get:
      tags:
        - users
      summary: 列出用户
    post:
      tags:
        - users
      summary: 创建用户
```

{% endcode %}

### 每个标签一页

当每个标签代表 API 中一个清晰的部分时，使用此布局。

当你想要概览页面、减少导航中的条目，并将相关端点放在同一页面时，它很适合。

使用此布局时，这两个操作会出现在为 `users` 标签。

### 每个操作一页

当你希望直接链接到各个端点时，使用此布局。

它适用于大型 API，或者当每个端点都需要在导航中拥有自己的页面时。

使用此布局时，GitBook 会为 `GET /users` 创建一个页面，并为 `POST /users`创建一个页面。这两个页面都会出现在 `users` 标签组下。

### 快速建议

选择 **每个标签一页** 适用于较小的 API，或者当每个标签都是一个清晰的部分时。

选择 **每个操作一页** 适用于较大的 API，或者当你希望为每个端点提供专门页面时。

### 控制生成的导航

在这两种布局中，GitBook 都会使用你的 OpenAPI 标签来组织参考文档。

要控制顺序、层级、页面标题、图标和描述，请参见 [组织你的 API 参考文档](/docs/documentation/zh/api-references/guides/structuring-your-api-reference.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/api-references/guides/openapi-layouts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.