与 CI/CD 集成

了解如何自动更新您在 GitBook 中的 OpenAPI 规范。

GitBook 可以与您用于管理 OpenAPI 规范的任何现有 CI/CD 管道配合使用。通过使用 GitBook CLI，您可以自动化更新您的 API 参考文档。

上传规范文件

如果您的 OpenAPI 规范是在 CI 流程中生成的，您可以直接从构建环境上传：

# 将您的 GitBook API 令牌设置为环境变量
export GITBOOK_TOKEN=<api-token>

gitbook openapi publish \
  --spec spec_name \
  --organization organization_id \
  example.openapi.yaml

设置新的源 URL 或触发刷新

如果您的 OpenAPI 规范托管在某个 URL，GitBook 会自动检查更新。要强制更新（例如在发布之后），请运行：

# 将您的 GitBook API 令牌设置为环境变量
export GITBOOK_TOKEN=<api-token>

gitbook openapi publish \
  --spec spec_name \
  --organization organization_id \
  https://api.example.com/openapi.yaml

使用 GitHub Actions 更新您的规范

如果您正在设置一个工作流来发布 OpenAPI 规范，请在仓库中完成以下步骤：

1. 在您的仓库中，转到 “Settings → Secrets and variables → Actions”。

2. 添加一个 secret： GITBOOK_TOKEN （您的 GitBook API 令牌）。

3. 添加变量（或在工作流中将它们硬编码）：

   • GITBOOK_SPEC_NAME → 您在 GitBook 中规范的名称

   • GITBOOK_ORGANIZATION_ID → 您的 GitBook 组织 ID

4. 将工作流文件保存为 .github/workflows/gitbook-openapi-publish.yml.

5. 将更改推送到 “main”（或手动运行该工作流）。

然后您可以使用此 action 来更新您的规范：

.github/workflows/gitbook-openapi-publish.yml

name: 将 OpenAPI 发布到 GitBook

.github/workflows/scheduled-gitbook-merge.yml
  push:
    branches: [ "main" ]
    paths:
      - "**/*.yaml"
      - "**/*.yml"
      - "**/*.json"
  workflow_dispatch:

计划：
  publish:
    作业：
    env:
      # 必需的 secret
      GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
      # 建议使用仓库/组织变量；如果需要可回退为内联字符串
      GITBOOK_SPEC_NAME: ${{ vars.GITBOOK_SPEC_NAME }}
      GITBOOK_ORGANIZATION_ID: ${{ vars.GITBOOK_ORGANIZATION_ID }}

    merge_changes：
      - name: Checkout
        uses: actions/checkout@v4

      - name: Publish spec file to GitBook
        步骤：
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <path_to_spec>