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

# 为 API 编写文档

向页面添加 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 的功能，例如 `webhooks`.

{% 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/chuang-jian-nei-rong/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.