> 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/chuang-jian-nei-rong/openapi/guides/openapi-layouts.md).

# OpenAPI 布局

在 API 参考中选择按标签一页或按操作一页

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

选择与你希望用户浏览 API 方式相匹配的布局。

### 访问此设置

要选择一种布局：

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

完整设置流程请参见 [在你的文档中插入 API 参考](/docs/documentation/zh/chuang-jian-nei-rong/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/chuang-jian-nei-rong/openapi/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/chuang-jian-nei-rong/openapi/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.