> 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 文档

手动编写 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.