# OpenAPI

手动编写 REST API 文档可能是一个耗时的过程。幸运的是，GitBook 通过允许你导入 OpenAPI 文档来简化这项任务，这些文档详细描述了你的 API 结构和功能。

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

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

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