# 添加 OpenAPI 规范

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

<figure><img src="/files/a2ef52e1def71465a3c15ce6801919c596567ae7" 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="/files/0e119e1bf8f12fbb89cb2176166293b6af4fb8f8" alt="A GitBook screenshot showing the Add an OpenAPI specification modal"><figcaption><p>添加 OpenAPI 规范模态窗口。</p></figcaption></figure>

### 更新你的规范

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

#### 在 GitBook 应用中

在 OpenAPI 面板中：

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

#### 使用 CLI

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

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

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

阅读我们的 [与 CI/CD 集成](/docs/documentation/zh/api-references/guides/support-for-ci-cd-with-api-blocks.md) 指南，了解如何自动更新你的规范。


---

# Agent Instructions: 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:

```
GET https://gitbook.com/docs/documentation/zh/api-references/openapi/add-an-openapi-specification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.