企业官网建设流程全解析

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 logout

API Key 在 Dashboard 的 Account > API Keys 页面生成。执行本文任何 registry 命令之前，请确认已用 API Key 完成认证。

发布 API 文档（publish）

将 API 文档写入 Registry 的核心命令是registry publish：

scalar 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

参数说明

必选参数：

可选参数（结合 CLI 命令参考 的registry publish段补全）：

其中--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 和 description：

scalar 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.yaml

Lint 检查

基于 Spectral 规则集检查文档规范问题：

scalar document lint ./openapi.yaml

还可以直接引用存放在 Registry 中的团队规则，实现“规则即代码、随注册表分发”：

scalar document lint ./openapi.yaml --rule https://registry.scalar.com/@your-team/rules/your-rule

Registry 中共享规则的创建与管理见 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 存为仓库 Secret（SCALAR_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/checkout@v6 - name: Use Node.js uses: actions/setup-node@v6 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 与自动化的单一事实来源），一条务实的终端工作流是：

1. scalar auth login --token ...建立认证（CI 中注入 Secret）；
2. scalar document validate+scalar document lint在本地/PR 阶段拦截问题；
3. scalar registry publish携带--version/--private等参数发布到目标 namespace；
4. 用scalar registry list/registry get核对发布结果；
5. 元数据变化用registry update轻量修正，下线资源用registry delete清理；
6. 多团队环境用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