Scalar Registry CLI 完全指南用命令行发布、管理与校验 API 文档【免费下载链接】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 CLI 指南 展开系统讲解如何通过scalar/cli以编程方式与 Scalar Registry 交互从认证、发布 OpenAPI/AsyncAPI 文档、管理文档元数据到本地校验、Lint 规则与团队切换直至将整条流水线接入 CI/CD。读完后你可以脱离 Dashboard 界面在终端和自动化脚本中完成 API 文档从“本地文件”到“团队共享注册表”的完整闭环。前提安装 CLI 并完成认证Registry CLI 所有命令都依赖有效的登录态。Scalar CLI 以 npm 包scalar/cli形式分发安装后scalar命令即可直接使用不想全局安装时也可以为每条命令加npx scalar/cli前缀执行详见 CLI 入门指南# 全局安装 npm -g install scalar/cli # 或者免安装执行 npx scalar/cli help注意系统中还有一个随git附带的scalar命令可能产生命名冲突。若确定不需要另一个 CLI可用npm -g --force install scalar/cli强制覆盖否则坚持使用npx或pnpm dlx方式执行即可。认证方式有两种参见 认证文档# 本地开发机打开 Dashboard 完成浏览器认证 scalar auth login # CI/CD 或自动化场景直接用 API Key 登录 scalar auth login --token your-secret-scalar-api-key # 查看当前登录用户 / 登出 scalar auth whoami scalar auth logoutAPI Key 在 Dashboard 的 Account API Keys 页面生成。执行本文任何 registry 命令之前请确认已用 API Key 完成认证。发布 API 文档publish将 API 文档写入 Registry 的核心命令是registry publishscalar registry publish ./openapi.yaml --namespace your-team --slug your-api该命令同时接受 OpenAPI 与 AsyncAPI 文档。格式判定发生在文档到达 Registry 服务端之后因此发布 AsyncAPI 事件 API 时使用完全相同的命令scalar registry publish ./asyncapi.yaml --namespace your-team --slug your-events-api参数说明必选参数参数说明file位置参数API 文档路径OpenAPI 或 AsyncAPI--namespaceScalar 团队的 namespace--slugRegistry 条目的唯一标识符不指定时默认取文档的 title可选参数结合 CLI 命令参考 的registry publish段补全参数说明--version versionAPI 版本号例如1.0.0--private将 API 设为私有默认false--force强制覆盖已存在的同名版本默认false--no-current发布后不将该版本设为 current 版本--bundle上传前先内联解析所有外部$ref引用--treeShake打包时剔除未使用的 components--urlMap打包时生成已解析 URL 的映射--fetchLimit limit打包阶段同时抓取外部引用的最大并发数其中--bundle系列选项对引用分散在多个文件的规范特别有用上传前 CLI 会先把所有外部引用解引用合并成单文件避免 Registry 侧拿到无法离线解析的$ref。典型用法示例# 基础发布 scalar registry publish api/openapi.json --namespace your-team --slug user-api # 指定版本并设为私有 scalar registry publish api/openapi.json --namespace your-team --slug user-api --version 1.0.0 --private # 强制更新已存在的版本 scalar registry publish api/openapi.json --namespace your-team --slug user-api --force管理 Registry 中的文档发布之后文档的日常维护同样可以全部在终端完成。列出团队下的所有文档scalar registry list --namespace your-team更新文档元数据无需重新上传文件仅修改 title 和 descriptionscalar registry update your-team your-api --title New Title --description New description删除文档scalar registry delete your-team your-api删除会移除该条目下所有版本请确认下游产品文档站、SDK 生成等是否依赖该文档再执行。拉取指定版本补充命令参考 中registry组还提供了get子命令可以从 Registry 反向拉取文档内容方便做版本对比或回填本地scalar registry get your-team your-api --version 1.0.0 --format yaml -o openapi.yaml--version指定文档版本缺省取 latest--format输出格式json或yaml默认json-o, --output输出文件缺省打印到 stdout校验与质量检查Validation and Quality发布前先做本地质量把关可以避免把坏文档推给整个团队。结构校验scalar document validate ./openapi.yamlLint 检查基于 Spectral 规则集检查文档规范问题scalar document lint ./openapi.yaml还可以直接引用存放在 Registry 中的团队规则实现“规则即代码、随注册表分发”scalar document lint ./openapi.yaml --rule https://registry.scalar.com/your-team/rules/your-ruleRegistry 中共享规则的创建与管理见 Rules 指南。AsyncAPI 文档的 Lint 与 Validate 差异这里有一个容易踩坑的细节scalar document lint同时支持 AsyncAPI。它会先检测文档类型对 AsyncAPI 文档改用 Spectral 的spectral:asyncapi规则集而不是spectral:oas因此报告出的问题都是真正适用于消息驱动 API 的而scalar document validate目前仅支持 OpenAPI——指向 AsyncAPI 文档时会直接报错并提示改用lint。至于把 AsyncAPI 文档发布进 Registry则一切照常。如果团队也需要validate支持 AsyncAPI可通过官方 issue 或支持邮箱向 Scalar 团队反馈。团队管理Team Management当你同属于多个团队时用team组切换当前活跃团队# 列出你加入的所有团队 scalar team list # 设置当前活跃团队--team 传团队 uid scalar team set --team team-uid多 API 仓库与 CI/CD 集成多 API 批量发布对于包含多个 API 的仓库CLI 天然适合写进脚本或流水线。原指南给出的最小示例是顺序发布多个文档# Example: Publish multiple APIs scalar registry publish ./apis/user-api/openapi.json --namespace your-team --slug user-api scalar registry publish ./apis/product-api/openapi.json --namespace your-team --slug product-api scalar registry publish ./apis/order-api/openapi.json --namespace your-team --slug order-api接入 GitHub Actions仓库内的 GitHub Actions 指南 提供了更完整的落地模板。核心思路是把 API Key 存为仓库 SecretSCALAR_API_KEY工作流中先校验、再登录、最后推送# .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该指南还覆盖了按分支区分 namespace 的环境化发布、Pull Request 上的提前校验、以及使用strategy.matrix批量发布多个 API 的写法。对多 API 仓库用 matrix 替代逐条手写命令是更稳的做法- name: Publish ${{ matrix.api.name }} run: | npx scalar/cli registry publish \ --namespace ${{ vars.SCALAR_NAMESPACE }} \ --slug ${{ matrix.api.slug }} \ ${{ matrix.api.file }}CLI 对环境变量有良好的支持认证凭据、namespace 均可通过 CI 变量注入从而实现对 API 文档的持续部署每次推送自动完成“校验 → Lint → 登录 → 发布”的完整链路。推荐工作流小结结合 Registry 概览 的定位Registry 是文档、SDK 与自动化的单一事实来源一条务实的终端工作流是scalar auth login --token ...建立认证CI 中注入 Secretscalar document validatescalar document lint在本地/PR 阶段拦截问题scalar registry publish携带--version/--private等参数发布到目标 namespace用scalar registry list/registry get核对发布结果元数据变化用registry update轻量修正下线资源用registry delete清理多团队环境用scalar team set切换上下文。所有命令的完整参数包括auth、document、project、schema等与 Registry 协作紧密的子命令组均可在 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），仅供参考