> 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/openapi.md).

# OpenAPI

手动编写 REST API 文档可能非常耗时。幸运的是，GitBook 允许你导入 OpenAPI 文档，从而简化了这项工作；这些文档详细说明了你的 API 结构和功能。

OpenAPI 规范（OAS）是开发者用于记录 REST API 的框架。它以 JSON 或 YAML 编写，概述了你所有的端点、参数、模式和身份验证方案。

导入到 GitBook 后，这些文档会被转换为可交互且可测试的 API 区块，以可视化方式呈现你的 API 方法——无论规范是作为文件提供还是从 URL 加载。

### OpenAPI 兼容性

GitBook 支持导入并渲染以下规范版本：

* [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) — 支持。
* [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md) — 支持。
* [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md) — 支持，包括仅限 OpenAPI 3.1 的功能，例如 `webhook`.

{% openapi src="<https://petstore3.swagger.io/api/v3/openapi.json>" path="/pet" method="post" %}
<https://petstore3.swagger.io/api/v3/openapi.json>
{% endopenapi %}

### 测试它（由 Scalar 提供支持）

GitBook 的 OpenAPI 区块也支持“测试它”功能，这使你的用户可以使用编辑器中填充的数据和参数来测试你的 API 方法。

由 [Scalar](https://scalar.com/)，你无需离开文档即可查看你的 API 方法实际运行。上面有一个示例。

#### 常见问题

<details>

<summary>为什么我的规范没有加载？</summary>

{% hint style="info" %}
**注意：** 此信息仅适用于 **通过 URL 添加的规范**.
{% endhint %}

如果你通过 URL 添加了规范，你的 API 必须 [允许跨源](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin) 来自你的文档站点的 GET 请求。在你的 API 的 CORS 设置中，允许文档托管所在的确切来源（例如， `https://your-site.gitbook.io` 或 `https://docs.example.com`）。\
\
如果你的端点是公开的并且不使用凭据，你也可以返回： `Access-Control-Allow-Origin: *`\ <br>

</details>


---

# 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/openapi.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.