2026/9/14 1:59:37
FEATURED · 精选文章 
Scalar Registry 与 GitHub Actions在 CI 流水线中自动校验并发布 OpenAPI 文档【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本篇指南讲解如何将 Scalar Registry 的文档发布流程集成到 GitHub Actions 中先完成 API Key 鉴权再通过scalar/cli实现校验—登录—发布的自动化链路并覆盖分支环境路由、Pull Request 校验、多 API 矩阵发布等四种典型工作流。读完本文你可以在自己的仓库中直接复制可用的 workflow 文件让 OpenAPI 文档随每次提交自动同步到 Registry驱动后续的 Docs 与 SDK 生成。为什么用 CI 推送 RegistryScalar Registry 是 OpenAPI 与 AsyncAPI 文档、JSON Schema、Spectral 规则的中心化存储源single source of truth提供 Git 集成、版本管理和私有/公开可见性控制见 documentation/guides/registry/index.md。手动上传文档难以保证仓库里的文档 Registry 里的文档而 GitHub Actions 可以把发布过程嵌入现有的代码评审流程只有main分支的合法变更才会推到生产环境Pull Request 阶段先做静态校验拦截问题。整条流水线依赖三样东西Scalar CLInpm 包scalar/cli二进制名scalar提供document validate、auth login、registry publish等命令完整命令参考见 documentation/guides/cli/commands.mdRegistry 的 API Key用于 CI 无交互环境下的鉴权GitHub Actions 的 Secrets / Variables分别承载密钥与命名空间等环境配置。准备 API KeySCALAR_API_KEYRegistry 发布需要在 CI 中完成认证。本地开发机通常直接用scalar auth login打开 Dashboard 完成浏览器鉴权而 CI 环境应使用 API Key 直接登录见 documentation/guides/cli/authentication.mdscalar auth login --token your-secret-scalar-api-keyAPI Key 的获取路径登录 Scalar Dashboard 后进入Account API Keys页面生成密钥然后在 GitHub 仓库的Settings Secrets and variables Actions中把它添加为名为SCALAR_API_KEY的 Repository Secret。对应地分支命名空间等敏感程度较低的配置可以放在 Variablesvars.*中例如SCALAR_NAMESPACE_PRODUCTION、SCALAR_NAMESPACE_DEVELOPMENT。注意Secret 只应注入到 workflow 的run或env中不要写进 workflow 文件本身npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }}是最常见的注入方式。基础工作流校验后发布最简单的场景是向main分支推送时先校验 OpenAPI 文档再发布到 Registry。将以下内容保存为.github/workflows/push-to-scalar-registry.yml# .github/workflows/push-to-scalar-registry.yml name: Push OpenAPI document to the Registry on: push: branches: - main jobs: push-to-scalar-registry: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Use Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate OpenAPI Document run: npx scalar/cli document validate api/openapi.json - name: Log in to Registry run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Push to Registry run: npx scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json逐步解析步骤命令作用Checkoutactions/checkoutv6拉取仓库代码得到api/openapi.jsonNode 环境actions/setup-nodev6node-version: 24提供运行 CLI 所需的 Node.js 运行时校验npx scalar/cli document validate file校验 OpenAPI 文档合法性失败则中止流水线避免把坏文档推上去登录npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }}用 API Key 完成无交互鉴权auth login还支持--email/--password参数见命令参考发布npx scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json将文档上传到your-team命名空间下的your-api条目关于registry publish除文档中出现的--namespace/--slug外CLI 还提供了一组更完整的选项摘自 documentation/guides/cli/commands.md 中的命令参考在 CI 中按需追加即可选项说明--slug slug注册表条目的 slug 标识缺省时回退为文档标题--namespace namespaceScalar 团队命名空间--version versionAPI 版本号如1.0.0--private设为私有 API默认 false--no-current发布后不将其设为当前版本--force强制覆盖已存在的同名版本默认 false--bundle上传前解析并打包所有外部引用--treeShake打包时移除未使用的 components--urlMap打包时生成已解析 URL 的映射--fetchLimit limit打包时的并发抓取上限npx scalar/cli ...的写法让 workflow 无需显式安装 CLI首次运行会自动拉取最新版本如果团队希望锁版本或减少重复下载也可以像下一节的写法那样先npm install -g scalar/cli再直接使用scalar命令。环境隔离按分支路由到不同命名空间对于区分 development / staging / production 的项目可以让同一个 workflow 在不同分支上发布到不同命名空间。核心手法是用paths过滤只触发 API 文档变更再根据github.ref条件地把目标命名空间写入$GITHUB_ENV供后续步骤复用。完整示例保存为.github/workflows/publish-openapi-document.yml# .github/workflows/publish-openapi-document.yml name: Publish OpenAPI Document on: push: paths: - api/**/*.yaml branches: - main - development jobs: publish: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Install Scalar CLI run: npm install -g scalar/cli - name: Authenticate Scalar env: SCALAR_API_KEY: ${{ secrets.SCALAR_API_KEY }} run: scalar auth login - name: Set production namespace if: github.ref refs/heads/main run: echo NAMESPACE${{ vars.SCALAR_NAMESPACE_PRODUCTION }} $GITHUB_ENV - name: Set development namespace if: github.ref refs/heads/development run: echo NAMESPACE${{ vars.SCALAR_NAMESPACE_DEVELOPMENT }} $GITHUB_ENV - name: Publish API run: scalar registry publish ./api/openapi.json --namespace $NAMESPACE --slug your-api这段工作流有三个值得注意的实现细节触发器过滤paths: api/**/*.yaml保证只有 API 目录下的变更才会触发发布branches限定只响应main与development鉴权方式差异这里没有使用--token参数而是把密钥放入env.SCALAR_API_KEY后执行裸命令scalar auth login。对照 documentation/guides/cli/authentication.md 可知auth login支持--token显式传参两种写法等价于参数注入与环境变量注入后者避免密钥出现在run命令文本中是不少团队的偏好命名空间条件注入两个if步骤互斥执行把vars.SCALAR_NAMESPACE_PRODUCTIONmain 分支或vars.SCALAR_NAMESPACE_DEVELOPMENTdevelopment 分支写入$GITHUB_ENV的NAMESPACE变量。$GITHUB_ENV中的变量对同一 Job 的后续步骤可见因此最后的scalar registry publish无需感知分支差异只需消费$NAMESPACE。如果两个分支都没命中例如未来误配置NAMESPACE为空发布会因命名空间无效而失败——这种快速失败行为正是期望的。Pull Request 校验合并前拦截坏文档对于希望在合并前就发现 OpenAPI 文档问题的团队可以单独建一个只校验、不发布的 workflow保存为.github/workflows/validate-openapi.yml# .github/workflows/validate-openapi.yml name: Validate OpenAPI on Pull Request on: pull_request: paths: - api/** jobs: validate: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate OpenAPI Document run: npx scalar/cli document validate api/openapi.json这个 workflow 不需要任何 Secret——校验完全在本地文档上执行。paths: api/**确保与 API 文档无关的 PR 不浪费 CI 资源。如果团队在 Registry 中沉淀了 Spectral 治理规则见 documentation/guides/registry/rules.md可以在校验步骤后追加一条 lint 步骤直接引用 Registry 中的规则集- name: Lint OpenAPI Document run: npx scalar/cli document lint api/openapi.json --rule https://registry.scalar.com/your-team/rules/your-ruledocument lint通过-r, --rule接收规则路径或 URL对 OpenAPI 文档运行 Spectral 的oas规则集文档中也可只校验不发布实现PR 卡质量、push 管发布的分工。多 API 仓库矩阵发布当仓库中同时维护多个 API如 user-api、product-api、order-api用 GitHub Actions 的strategy.matrix可以为每个 API 并行生成一个 job每个 job 独立校验并独立发布。完整示例保存为.github/workflows/publish-multiple-apis.yml# .github/workflows/publish-multiple-apis.yml name: Publish Multiple APIs on: push: branches: - main paths: - apis/** jobs: publish-apis: runs-on: ubuntu-latest strategy: matrix: api: - name: user-api file: apis/user-api/openapi.json slug: user-api - name: product-api file: apis/product-api/openapi.json slug: product-api - name: order-api file: apis/order-api/openapi.json slug: order-api steps: - name: Checkout repository uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate ${{ matrix.api.name }} run: npx scalar/cli document validate ${{ matrix.api.file }} - name: Login to Registry run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Publish ${{ matrix.api.name }} run: | npx scalar/cli registry publish \ --namespace ${{ vars.SCALAR_NAMESPACE }} \ --slug ${{ matrix.api.slug }} \ ${{ matrix.api.file }}矩阵设计的要点矩阵维度即 API 清单每个矩阵项声明name用于步骤标题展示、file仓库内文档路径、slugRegistry 条目标识三元组。新增 API 时只需在矩阵中追加一项workflow 本身不用改并行与故障隔离GitHub Actions 会为矩阵项各起一个 jobuser-api的校验失败不会阻塞product-api的发布日志也按Validate user-api、Publish order-api等命名可直接定位统一命名空间所有 API 使用同一个vars.SCALAR_NAMESPACE变量便于在 Dashboard 中按团队聚合查看命令续行写法registry publish步骤使用\跨行书写等价于单行npx scalar/cli registry publish --namespace ns --slug slug file多参数场景下可读性更好。如果某个 API 的文档存在大量外部引用跨文件$ref发布时可追加--bundle让 CLI 先解析打包外部引用再上传见 documentation/guides/registry/cli.md 中关于 Registry 管理的说明。配置清单与后续步骤把四种工作流组合起来一个完整的 Registry CI 方案需要的配置项是配置项存放位置用途SCALAR_API_KEYRepository Secrets所有发布/认证步骤的鉴权密钥SCALAR_NAMESPACE/SCALAR_NAMESPACE_PRODUCTION/SCALAR_NAMESPACE_DEVELOPMENTRepository Variables目标团队命名空间可随分支切换node-version: 24workflowsetup-node步骤文档示例采用的 Node 运行时版本paths过滤workflowon触发器仅 API 文档变更触发流水线落地建议的顺序先用基础工作流跑通单文档发布再视团队规模叠加 PR 校验、分支路由或矩阵发布。Registry 中的文档一旦就位就可以在同一数据源之上生成 API Docs 与 SDK参见 documentation/guides/registry/getting-started.md 与 documentation/guides/registry/cli.md。更多相关文档documentation/guides/registry/github-actions.md本文对应的官方指南原文documentation/guides/registry/gitlab-ci.mdGitLab CI 环境下的同类集成方案documentation/guides/cli/commands.mdscalar/cli全量命令与参数参考documentation/guides/registry/cli.mdRegistry 的 CLI 操作指南发布、列表、更新、删除、团队管理。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Scalar Registry 与 GitHub Actions：在 CI 流水线中自动校验并发布 OpenAPI 文档
Scalar Registry 与 GitHub Actions在 CI 流水线中自动校验并发布 OpenAPI 文档【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar本篇指南讲解如何将 Scalar Registry 的文档发布流程集成到 GitHub Actions 中先完成 API Key 鉴权再通过scalar/cli实现校验—登录—发布的自动化链路并覆盖分支环境路由、Pull Request 校验、多 API 矩阵发布等四种典型工作流。读完本文你可以在自己的仓库中直接复制可用的 workflow 文件让 OpenAPI 文档随每次提交自动同步到 Registry驱动后续的 Docs 与 SDK 生成。为什么用 CI 推送 RegistryScalar Registry 是 OpenAPI 与 AsyncAPI 文档、JSON Schema、Spectral 规则的中心化存储源single source of truth提供 Git 集成、版本管理和私有/公开可见性控制见 documentation/guides/registry/index.md。手动上传文档难以保证仓库里的文档 Registry 里的文档而 GitHub Actions 可以把发布过程嵌入现有的代码评审流程只有main分支的合法变更才会推到生产环境Pull Request 阶段先做静态校验拦截问题。整条流水线依赖三样东西Scalar CLInpm 包scalar/cli二进制名scalar提供document validate、auth login、registry publish等命令完整命令参考见 documentation/guides/cli/commands.mdRegistry 的 API Key用于 CI 无交互环境下的鉴权GitHub Actions 的 Secrets / Variables分别承载密钥与命名空间等环境配置。准备 API KeySCALAR_API_KEYRegistry 发布需要在 CI 中完成认证。本地开发机通常直接用scalar auth login打开 Dashboard 完成浏览器鉴权而 CI 环境应使用 API Key 直接登录见 documentation/guides/cli/authentication.mdscalar auth login --token your-secret-scalar-api-keyAPI Key 的获取路径登录 Scalar Dashboard 后进入Account API Keys页面生成密钥然后在 GitHub 仓库的Settings Secrets and variables Actions中把它添加为名为SCALAR_API_KEY的 Repository Secret。对应地分支命名空间等敏感程度较低的配置可以放在 Variablesvars.*中例如SCALAR_NAMESPACE_PRODUCTION、SCALAR_NAMESPACE_DEVELOPMENT。注意Secret 只应注入到 workflow 的run或env中不要写进 workflow 文件本身npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }}是最常见的注入方式。基础工作流校验后发布最简单的场景是向main分支推送时先校验 OpenAPI 文档再发布到 Registry。将以下内容保存为.github/workflows/push-to-scalar-registry.yml# .github/workflows/push-to-scalar-registry.yml name: Push OpenAPI document to the Registry on: push: branches: - main jobs: push-to-scalar-registry: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Use Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate OpenAPI Document run: npx scalar/cli document validate api/openapi.json - name: Log in to Registry run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Push to Registry run: npx scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json逐步解析步骤命令作用Checkoutactions/checkoutv6拉取仓库代码得到api/openapi.jsonNode 环境actions/setup-nodev6node-version: 24提供运行 CLI 所需的 Node.js 运行时校验npx scalar/cli document validate file校验 OpenAPI 文档合法性失败则中止流水线避免把坏文档推上去登录npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }}用 API Key 完成无交互鉴权auth login还支持--email/--password参数见命令参考发布npx scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json将文档上传到your-team命名空间下的your-api条目关于registry publish除文档中出现的--namespace/--slug外CLI 还提供了一组更完整的选项摘自 documentation/guides/cli/commands.md 中的命令参考在 CI 中按需追加即可选项说明--slug slug注册表条目的 slug 标识缺省时回退为文档标题--namespace namespaceScalar 团队命名空间--version versionAPI 版本号如1.0.0--private设为私有 API默认 false--no-current发布后不将其设为当前版本--force强制覆盖已存在的同名版本默认 false--bundle上传前解析并打包所有外部引用--treeShake打包时移除未使用的 components--urlMap打包时生成已解析 URL 的映射--fetchLimit limit打包时的并发抓取上限npx scalar/cli ...的写法让 workflow 无需显式安装 CLI首次运行会自动拉取最新版本如果团队希望锁版本或减少重复下载也可以像下一节的写法那样先npm install -g scalar/cli再直接使用scalar命令。环境隔离按分支路由到不同命名空间对于区分 development / staging / production 的项目可以让同一个 workflow 在不同分支上发布到不同命名空间。核心手法是用paths过滤只触发 API 文档变更再根据github.ref条件地把目标命名空间写入$GITHUB_ENV供后续步骤复用。完整示例保存为.github/workflows/publish-openapi-document.yml# .github/workflows/publish-openapi-document.yml name: Publish OpenAPI Document on: push: paths: - api/**/*.yaml branches: - main - development jobs: publish: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Install Scalar CLI run: npm install -g scalar/cli - name: Authenticate Scalar env: SCALAR_API_KEY: ${{ secrets.SCALAR_API_KEY }} run: scalar auth login - name: Set production namespace if: github.ref refs/heads/main run: echo NAMESPACE${{ vars.SCALAR_NAMESPACE_PRODUCTION }} $GITHUB_ENV - name: Set development namespace if: github.ref refs/heads/development run: echo NAMESPACE${{ vars.SCALAR_NAMESPACE_DEVELOPMENT }} $GITHUB_ENV - name: Publish API run: scalar registry publish ./api/openapi.json --namespace $NAMESPACE --slug your-api这段工作流有三个值得注意的实现细节触发器过滤paths: api/**/*.yaml保证只有 API 目录下的变更才会触发发布branches限定只响应main与development鉴权方式差异这里没有使用--token参数而是把密钥放入env.SCALAR_API_KEY后执行裸命令scalar auth login。对照 documentation/guides/cli/authentication.md 可知auth login支持--token显式传参两种写法等价于参数注入与环境变量注入后者避免密钥出现在run命令文本中是不少团队的偏好命名空间条件注入两个if步骤互斥执行把vars.SCALAR_NAMESPACE_PRODUCTIONmain 分支或vars.SCALAR_NAMESPACE_DEVELOPMENTdevelopment 分支写入$GITHUB_ENV的NAMESPACE变量。$GITHUB_ENV中的变量对同一 Job 的后续步骤可见因此最后的scalar registry publish无需感知分支差异只需消费$NAMESPACE。如果两个分支都没命中例如未来误配置NAMESPACE为空发布会因命名空间无效而失败——这种快速失败行为正是期望的。Pull Request 校验合并前拦截坏文档对于希望在合并前就发现 OpenAPI 文档问题的团队可以单独建一个只校验、不发布的 workflow保存为.github/workflows/validate-openapi.yml# .github/workflows/validate-openapi.yml name: Validate OpenAPI on Pull Request on: pull_request: paths: - api/** jobs: validate: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate OpenAPI Document run: npx scalar/cli document validate api/openapi.json这个 workflow 不需要任何 Secret——校验完全在本地文档上执行。paths: api/**确保与 API 文档无关的 PR 不浪费 CI 资源。如果团队在 Registry 中沉淀了 Spectral 治理规则见 documentation/guides/registry/rules.md可以在校验步骤后追加一条 lint 步骤直接引用 Registry 中的规则集- name: Lint OpenAPI Document run: npx scalar/cli document lint api/openapi.json --rule https://registry.scalar.com/your-team/rules/your-ruledocument lint通过-r, --rule接收规则路径或 URL对 OpenAPI 文档运行 Spectral 的oas规则集文档中也可只校验不发布实现PR 卡质量、push 管发布的分工。多 API 仓库矩阵发布当仓库中同时维护多个 API如 user-api、product-api、order-api用 GitHub Actions 的strategy.matrix可以为每个 API 并行生成一个 job每个 job 独立校验并独立发布。完整示例保存为.github/workflows/publish-multiple-apis.yml# .github/workflows/publish-multiple-apis.yml name: Publish Multiple APIs on: push: branches: - main paths: - apis/** jobs: publish-apis: runs-on: ubuntu-latest strategy: matrix: api: - name: user-api file: apis/user-api/openapi.json slug: user-api - name: product-api file: apis/product-api/openapi.json slug: product-api - name: order-api file: apis/order-api/openapi.json slug: order-api steps: - name: Checkout repository uses: actions/checkoutv6 - name: Setup Node.js uses: actions/setup-nodev6 with: node-version: 24 - name: Validate ${{ matrix.api.name }} run: npx scalar/cli document validate ${{ matrix.api.file }} - name: Login to Registry run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - name: Publish ${{ matrix.api.name }} run: | npx scalar/cli registry publish \ --namespace ${{ vars.SCALAR_NAMESPACE }} \ --slug ${{ matrix.api.slug }} \ ${{ matrix.api.file }}矩阵设计的要点矩阵维度即 API 清单每个矩阵项声明name用于步骤标题展示、file仓库内文档路径、slugRegistry 条目标识三元组。新增 API 时只需在矩阵中追加一项workflow 本身不用改并行与故障隔离GitHub Actions 会为矩阵项各起一个 jobuser-api的校验失败不会阻塞product-api的发布日志也按Validate user-api、Publish order-api等命名可直接定位统一命名空间所有 API 使用同一个vars.SCALAR_NAMESPACE变量便于在 Dashboard 中按团队聚合查看命令续行写法registry publish步骤使用\跨行书写等价于单行npx scalar/cli registry publish --namespace ns --slug slug file多参数场景下可读性更好。如果某个 API 的文档存在大量外部引用跨文件$ref发布时可追加--bundle让 CLI 先解析打包外部引用再上传见 documentation/guides/registry/cli.md 中关于 Registry 管理的说明。配置清单与后续步骤把四种工作流组合起来一个完整的 Registry CI 方案需要的配置项是配置项存放位置用途SCALAR_API_KEYRepository Secrets所有发布/认证步骤的鉴权密钥SCALAR_NAMESPACE/SCALAR_NAMESPACE_PRODUCTION/SCALAR_NAMESPACE_DEVELOPMENTRepository Variables目标团队命名空间可随分支切换node-version: 24workflowsetup-node步骤文档示例采用的 Node 运行时版本paths过滤workflowon触发器仅 API 文档变更触发流水线落地建议的顺序先用基础工作流跑通单文档发布再视团队规模叠加 PR 校验、分支路由或矩阵发布。Registry 中的文档一旦就位就可以在同一数据源之上生成 API Docs 与 SDK参见 documentation/guides/registry/getting-started.md 与 documentation/guides/registry/cli.md。更多相关文档documentation/guides/registry/github-actions.md本文对应的官方指南原文documentation/guides/registry/gitlab-ci.mdGitLab CI 环境下的同类集成方案documentation/guides/cli/commands.mdscalar/cli全量命令与参数参考documentation/guides/registry/cli.mdRegistry 的 CLI 操作指南发布、列表、更新、删除、团队管理。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
