> 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 布局

当你插入一个 **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:
      标签：
        - users
      摘要：列出用户
    post:
      标签：
        - users
      摘要：创建用户
```

{% 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.