# 添加 OpenAPI 规范

如果你有一个 OpenAPI 规范，可以通过直接上传文件、链接到托管 URL，或使用 [GitBook CLI](https://gitbook.com/docs/developers/integrations/reference).

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2F6pg8vIZeVQESjhTw5yI2%2Fgenerate-api-docs%402x.png?alt=media&#x26;token=6b72cd8d-7943-465a-88d5-04f8f0f13245" alt="A GitBook screenshot showing the modal for generating API docs automatically"><figcaption></figcaption></figure>

### 如何添加规范

1. 打开 **OpenAPI** 侧边栏中的部分
2. 点击 **添加规范**
3. 为你的规范命名。这有助于识别它，尤其是在你管理多个规范时
4. 请选择以下其中一种：
   * 上传文件（例如： *openapi.yaml*)
   * 输入一个托管规范的 URL
   * 使用 CLI 发布该规范

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FpTRwMrbHyYlKZy07CsAp%2Fapi_spec_modal%402x.png?alt=media&#x26;token=77edbf02-aed7-43cc-a1e3-9a61fc001271" alt="A GitBook screenshot showing the Add an OpenAPI specification modal"><figcaption><p>添加 OpenAPI 规范弹窗。</p></figcaption></figure>

### 更新你的规范

无论 OpenAPI 规范最初是如何添加的，你都可以随时使用 GitBook UI 或 CLI 更新它。

#### 在 GitBook 应用中

在 OpenAPI 面板中：

* 如果你的规范链接到一个 URL：
  * GitBook 会自动检查更新 **每 6 小时**.
  * 要立即获取更新，请点击 **检查更新**.
* 如果你的规范是以文件形式上传的：
  * 点击 **更新** 以上传新版本。
* 你可以通过点击 **编辑** 在面包屑操作菜单中，将来源从文件切换为 URL。

#### 使用 CLI

使用相同的命令来更新你的规范：

```bash
gitbook openapi publish --spec api-spec-name --organization organization_id <path-or-url>
```

你也可以使用 CLI 来 **检查更新** 方法是针对同一个 URL 运行 publish 命令。

阅读我们的 [support-for-ci-cd-with-api-blocks](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/api-references/guides/support-for-ci-cd-with-api-blocks "mention") 指南，了解如何自动更新你的规范。