为 API 编写文档

向页面添加 OpenAPI 规范，并让用户使用交互式块直接在页面上测试端点。

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

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

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

OpenAPI 兼容性

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

• Swagger 2.0 — 支持。
• OpenAPI 3.0 — 支持。
• OpenAPI 3.1 — 支持，包括仅限 OpenAPI 3.1 的功能，例如 webhooks.

Add a new pet to the store.

post

Add a new pet to the store.

必需范围

此端点需要以下范围：

• : modify pets in your account
• : read your pets

授权

OAuth2implicit必填

Authorization URL:

请求体

idinteger · int64可选Example: 10

namestring必填Example: doggie

photoUrlsstring[]必填

statusstring · enum可选

pet status in the store

可能的值:

响应

200

Successful operation

idinteger · int64可选Example: 10

namestring必填Example: doggie

photoUrlsstring[]必填

statusstring · enum可选

pet status in the store

可能的值:

400

Invalid input

422

Validation exception

default

Unexpected error

post/pet

POST /api/v3/pet HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "text"
  ],
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "status": "available"
}

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "text"
  ],
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "status": "available"
}

试用它（由 Scalar 提供支持）

GitBook 的 OpenAPI 块也支持“试用它”功能，它允许你的用户使用从编辑器中填写的数据和参数来测试你的 API 方法。

由……驱动 Scalar，你无需离开文档即可查看你的 API 方法运行情况。请参见上面的示例。

常见问题

为什么我的规范没有加载？

注意： 此信息仅适用于 通过 URL 添加的规范.

如果你是通过 URL 添加的规范，你的 API 必须 允许跨域 来自你的文档站点的 GET 请求。在你的 API 的 CORS 设置中，允许文档托管所在的确切来源（例如， https://your-site.gitbook.io 或 https://docs.example.com）。 如果你的端点是公开的且不使用凭据，你也可以返回： Access-Control-Allow-Origin: *