> 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/openapi.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
