与 CI/CD 集成

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

GitBook 可以与你现有的任何 CI/CD 流水线配合使用，用于管理你的 OpenAPI 规范。通过使用 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. 添加一个密钥： GITBOOK_TOKEN （你的 GitBook API 令牌）。

3. 添加变量（或者也可以直接在工作流中硬编码它们）：

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

   • GITBOOK_ORGANIZATION_ID → 你的 GitBook 组织 ID

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

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

然后你就可以使用此操作来更新你的规范：

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

name: 将 OpenAPI 发布到 GitBook

on:
  push:
    branches: [ "main" ]
    paths:
      - "**/*.yaml"
      - "**/*.yml"
      - "**/*.json"
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      # 所需密钥
      GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
      # 优先使用仓库/组织变量；如果你愿意，也可以回退为内联字符串
      GITBOOK_SPEC_NAME: ${{ vars.GITBOOK_SPEC_NAME }}
      GITBOOK_ORGANIZATION_ID: ${{ vars.GITBOOK_ORGANIZATION_ID }}

    steps:
      - name: 检出
        uses: actions/checkout@v4

      - name: 将规范文件发布到 GitBook
        run: |
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <规范文件路径>