拓冰网站定制 
Scalar Registry用 Git 深度集成为 OpenAPI 与 AsyncAPI 文档构建单一事实来源【免费下载链接】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/scalarScalar Registry 是 Scalar 开源 API 平台中的集中式 API 注册表用于存储、版本化并统一管理 OpenAPI/AsyncAPI 文档、JSON Schema 与 Spectral 规则。阅读本文可以完整掌握 Registry 的定位与核心能力并学会通过 Dashboard、CLI 以及 GitHub Actions / GitLab CI 把 API 文档发布、校验和治理流程接入团队现有的 Git 工作流使 API 文档、SDK 与自动化始终消费同一份来源。为什么需要 RegistryAPI 管理的复杂性会随着团队规模迅速膨胀真实来源在哪里、版本如何管理、谁有访问权限、下游消费者如何发现更新——这些问题没有统一答案时文档、SDK 和自动化脚本就会各自为政、逐渐失真。Registry 给团队提供了一个放置 OpenAPI 与 AsyncAPI 文档的中央位置以及围绕它们的全部工作流。正如文档首页 documentation/guides/registry/index.md 所述一旦 API 文档进入 Registry就可以从同一份来源驱动文档Docs、SDK 生成、发布和自动化无需在多处复制粘贴。六大核心能力原文档列出的六个功能点构成本篇后续所有实操章节的主线能力说明对应实操章节Single source of truth单一事实来源API 文档、Schema、规则集中存放在一个受管理的位置下文全部章节Git integrationGit 集成将 Registry 接入仓库工作流更新遵循团队既有的评审流程CI/CD 集成OpenAPI and AsyncAPI对 OpenAPI 与 AsyncAPI 文档做版本化并发布供文档、SDK 与自动化消费CLI 发布JSON Schema support把共享 Schema 与依赖它的 API 文档一起管理Schema 管理Spectral rules存放规则支撑一致的 API 治理与校验工作流规则与 LintPrivate or public控制 API 文档是内部使用、团队共享还是公开各资源的访问控制从 Registry 生成 API 文档与 SDKRegistry 是 Scalar 各产品之间的文档总线。在 Dashboard 上点击几次即可基于 Registry 中的文档生成 API 文档API References文档与 OpenAPI 变更保持连接更新直接从来源流向已发布的文档页面。基于同一份 OpenAPI 文档还能生成 SDK让客户端库始终与 API 变更保持一致——Registry 负责维护来源文档与生成工具之间的连接。生成 API 文档的完整流程见 API References 入门 与 Docs 入门生成 SDK 的完整流程见 SDK Generator 入门支持的事件驱动文档格式见 AsyncAPI 说明这种一份文档驱动一切的模式在仓库中也能找到直接证据README.md 中的示例演示了把 API Reference 的url直接指向 Registry 上的文档地址registry.scalar.com/scalar/apis/galaxy?formatjson即文档页面消费的是 Registry 中版本化的文档资源而非本地快照。快速开始创建账号与上传第一份文档Registry 属于 Scalar 托管产品需要先注册账号。流程如下详见 Getting Started 指南注册/登录 Scalar 账号Dashboard 位于dashboard.scalar.com。登录后可通过三种方式操作 RegistryDashboard网页端管理CLI终端与 CI 中程序化操作见 Registry CLI 指南GitHub Actions仓库自动化推送见 GitHub Actions 指南。通过 Dashboard 上传 API 文档上传操作的完整步骤来自 Upload 指南在 Dashboard 右侧面板点击Import API或进入侧边栏 Products 下的 Registry 页面点击Create new API可上传任意版本的 OpenAPI 或 AsyncAPI包括 Swagger 2.0甚至 Postman Collection。Postman 导入能力在仓库中对应开源的转换包 packages/postman-to-openapi其convert函数负责把 Postman 集合转为标准 OpenAPI 文档isPostmanCollection可用于判断输入是否为 Postman 集合上传成功后API 文档即位于你所在团队的命名空间namespace之下。更新与删除文档更新使用 Scalar 的 OpenAPI Editor或从 Registry 页面点击Edit Document编辑文档。完成编辑后点击右上角Publish即可向 Registryupsert 一个新版本——同一版本会被覆盖更新新版本会被追加删除可从 Registry 的 Overview 页面删除文档但文档明确提醒删除前要考虑下游影响因为 Docs、SDK、自动化都可能依赖该文档资源。通过 CLI 管理 RegistryCLI 是 Registry 面向终端与 CI 的接口。执行任何命令前需先通过 API key 完成 CLI 认证scalar auth login或scalar auth login --token token直接指定令牌。发布 API 文档scalar registry publishscalar registry publish ./openapi.yaml --namespace your-team --slug your-apipublish同时接受 OpenAPI 与 AsyncAPI 文档。文档格式在到达 Registry 时自动识别因此两类文档使用完全相同的命令scalar registry publish ./asyncapi.yaml --namespace your-team --slug your-events-api必填参数参数说明fileAPI 文档路径位置参数--namespace你的 Scalar 团队命名空间--slugRegistry 条目的唯一标识符未指定时默认取文档 title可选参数参数说明--versionAPI 版本号例如0.1.0--private将 API 设为私有默认false--force强制覆盖已存在的版本默认false示例# 基础发布 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文档管理list / update / delete# 查看团队名下所有 Registry API scalar registry list --namespace your-team # 只更新标题与描述无需重新上传文件 scalar registry update your-team your-api --title New Title --description New description # 从 Registry 删除文档 scalar registry delete your-team your-api发布前的校验与 Lint# 校验 OpenAPI 文档 scalar document validate ./openapi.yaml # 使用 Spectral 规则做 lint scalar document lint ./openapi.yaml # 使用 Registry 中存放的 Rules scalar document lint ./openapi.yaml --rule https://registry.scalar.com/your-team/rules/your-rule一个值得注意的行为差异原文档以 NOTE 形式强调scalar document lint支持 AsyncAPI——它会自动识别文档类型对 AsyncAPI 文档运行 Spectral 的spectral:asyncapi规则集而不是spectral:oas保证报告的问题确实适用于该文档而scalar document validate目前仅支持 OpenAPI指向 AsyncAPI 文档时会停止并提示改用lint。向 Registry 发布 AsyncAPI 文档不受影响一切照常。多团队与多 API 场景如果你属于多个团队可以切换当前激活的团队# 列出你所在的全部团队 scalar team list # 设置激活团队 scalar team set --team team-uid仓库中包含多个 API 时可以在脚本或 CI/CD 中批量发布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管理共享 JSON SchemaRegistry 中的 Schema 允许把独立的 JSON Schema 对象发布到 OpenAPI 文档之外。与内嵌在 OpenAPI 文档中的 Schema 不同Scalar Schemas 具备四个特征来自 Schemas 指南Standalone独立独立于任何特定 API 管理Reusable可复用可被 Registry 中多个 API 引用Versioned版本化每个 Schema 有独立于 API 的版本线Shareable可共享可公开共享也可在团队内保持私有。创建并配置 Schema在 Dashboard 左侧边栏 Registry Schemas 下点击 New创建。需要配置的元数据配置项说明Schema Name描述其用途的名称如 User Profile、Payment MethodDescription该 JSON Schema 定义了什么、应如何使用Version初始版本如0.1.0、1.0.0后续可随发布迭代Namespace发布到的团队命名空间决定引用该 Schema 的 Registry 路径Schema AccessPublic任何人可通过 Registry URL 引用Private仅受邀用户与 access group 可访问引用在Edit标签页的 Schema 编辑器中定义 JSON Schema 本体。文档给出的示例Draft 2020-12{ $schema: https://json-schema.org/draft/2020-12/schema, type: object, title: User Profile, description: A user profile schema with contact information, properties: { id: { type: string, format: uuid, description: Unique identifier for the user }, email: { type: string, format: email, description: Users email address }, name: { type: object, properties: { first: { type: string, minLength: 1 }, last: { type: string, minLength: 1 } }, required: [first, last] }, createdAt: { type: string, format: date-time } }, required: [id, email, name] }点击Publish后即可获得用于引用的 Registry 路径registry.scalar.com/your-team/schemas/your-schema-nameversion用 sha 精确钉住版本文档中任何可以写 version 的位置都可以改写 sha——既可以是文档内容 sha也可以是其来源的 Git commitregistry.scalar.com/your-team/schemas/your-schema-name03e959a解析规则与原文明确的约束sha 支持前缀6 到 64 个十六进制字符匹配方式类似 git前缀匹配到多个文档时返回 404 而不是猜测版本永远优先与既有版本匹配的值仍解析到该版本公开文档的完整 64 位内容 sha 是不可变的会以长生命周期缓存提供服务该寻址方式对 API 文档同样适用/your-team/apis/…sha。在 API 文档中引用 Schema发布后可在 OpenAPI 文档中用$ref引用实现同一 JSON Schema 定义跨多个 API 复用同命名空间内的相对引用components: schemas: User: $ref: your-team/schemas/user1.0.0跨命名空间或公共 Schema 的完整 URL 引用components: schemas: User: $ref: https://registry.scalar.com/other-namespace/schemas/user1.0.0完整示例——在 OpenAPI 文档中使用 Schemaopenapi: 3.1.0 info: title: User API version: 1.0.0 paths: /users: get: responses: 200: description: List of users content: application/json: schema: type: array items: $ref: your-team/schemas/user1.0.0用 CLI 管理 Schema# 认证二选一 scalar auth login scalar auth login --token your-api-token # 发布 Schema scalar schema publish ./schema.json --namespace your-team --name user --version 1.0.0 # 列出命名空间下的所有 Schema含版本与访问级别 scalar schema list --namespace your-team # 更新元数据无需重新上传文件 scalar schema update --namespace your-team --name user --description Updated user profile schema # 删除某个版本的 Schema scalar schema delete --namespace your-team --name user --version 1.0.0scalar schema publish的参数参数必填说明file是JSON Schema 文件路径--namespace是团队命名空间--name是Schema 名称标识--version否版本号未指定时默认为0.0.1--private否设为私有默认false--force否强制覆盖已有版本默认false注意删除某个 Schema 版本会打断所有 OpenAPI 文档中对它的引用删除前务必先更新全部引用。Schema 最佳实践原文档给出的工程实践建议版本化采用语义化版本破坏性变更升 major新增可选属性升 minor修正与澄清升 patchSchema 设计保持聚焦与可复用避免只能用于单一场景的过具体 Schema属性命名要有描述性并附description善用format、pattern、minLength等校验能力复杂嵌套结构用$defs组织访问控制跨团队/组织共享的数据模型用 public组织内部数据模型用 private同一数据的内部表示与对外表示考虑拆成不同 Schema组织方式全库命名规范一致用命名模式归类相关 Schema如user-*、payment-*、address-*并写清描述。用 Spectral 规则做 API 治理Registry 中的 Rules 用于以 Spectral 兼容的规则集对 OpenAPI 文档做 lint 与校验可跨托管的 API 与 Schema 使用。创建规则在 Dashboard 侧边栏 Rules 下点击 New创建。新建的规则默认继承 Spectral OSS 规则集extends: spectral:oas rules: {}这提供了 OpenAPI lint 的坚实基础并支持三种定制方式扩展其他规则集、添加自定义规则、覆盖既有规则。规则的访问控制与其他 Registry 资源一致规则分两档Public Rules任何人可通过 Registry 路径访问适合开源项目或与社区共享 lint 标准Private Rules限定在组织内部可共享给特定 access group适合内部 API 标准与公司级 lint 要求。访问控制在规则的 Overview 页面管理方式与其他 Registry 资源相同。用 CLI 应用规则# 默认 lint scalar document lint ./openapi.yaml # 使用 Registry 中的特定规则 scalar document lint ./openapi.yaml --rule https://registry.scalar.com/your-team/rules/your-rule # 使用本地规则文件 scalar document lint ./openapi.yaml --rule ./my-custom-ruleset.yamlGit 集成GitHub ActionsRegistry 的 Git 集成让文档更新遵循仓库既有的评审流程。完整参考见 GitHub Actions 指南。基础工作流验证并推送 OpenAPI 文档到 Registry# .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按环境部署针对 development/staging/production 多环境场景工作流可按分支切换命名空间main分支发布到SCALAR_NAMESPACE_PRODUCTIONdevelopment分支发布到SCALAR_NAMESPACE_DEVELOPMENT两个分支均通过paths: api/**/*.yaml触发。发布前先执行document validate认证则通过环境变量SCALAR_API_KEY完成scalar auth login。其他模式指南中还给出了两套可直接套用的模式Pull Request 校验在pull_request事件中对api/**路径变更运行npx scalar/cli document validate把校验前移到合并之前多 API 仓库用strategy.matrix并行处理多个 API示例矩阵覆盖user-api、product-api、order-api每个 API 独立执行校验 → 登录 → 发布namespace 由仓库变量SCALAR_NAMESPACE注入。SCALAR_API_KEY在 Dashboard 的user/api-keys页面获取并添加到 GitHub 仓库的 Secrets 中。Git 集成GitLab CI/CDGitLab 侧的等价方案见 GitLab CI/CD 指南。基础流水线stages: - validate - deploy validate_openapi: stage: validate image: node:20 script: - npx scalar/cli document validate api/openapi.json rules: - if: $CI_COMMIT_BRANCH $CI_DEFAULT_BRANCH push_to_scalar_registry: stage: deploy image: node:20 script: - npx scalar/cli auth login --token $SCALAR_API_KEY - npx scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json rules: - if: $CI_COMMIT_BRANCH $CI_DEFAULT_BRANCH needs: - validate_openapi扩展模式按环境部署deploy_production默认分支触发environment: production与deploy_developmentdevelopment分支触发共用同一个validate_openapi校验阶段各自使用SCALAR_NAMESPACE_PRODUCTION/SCALAR_NAMESPACE_DEVELOPMENTMerge Request 校验在merge_request_event且api/**有变更时运行document validate在合并前拦截不合规文档多 API 仓库两种写法——用 YAML 锚点模板validate_template/deploy_template为每个 API 生成成对的 validate/deploy job或更简洁的parallel: matrix方案用一个validate_apis与一个deploy_apis并行 job 覆盖所有 API变量配置在项目的 Settings → CI/CD → Variables 中配置SCALAR_API_KEY建议 masked与SCALAR_NAMESPACE或分环境的SCALAR_NAMESPACE_PRODUCTION/SCALAR_NAMESPACE_DEVELOPMENT。小结Registry 的价值链条可以概括为来源OpenAPI/AsyncAPI 文档、独立 JSON Schema、Spectral 规则三类资源统一存放各自带版本与访问控制流转通过 Dashboard 的 Edit/Publishupsert 语义或 CLI 的publish/force参数控制版本演进通过 sha 钉住精确快照治理validate保证结构正确lint含 AsyncAPI 自动识别规则集保证风格一致消费API 文档、SDK 与下游自动化从同一份 Registry 来源取数Git 工作流GitHub Actions / GitLab CI保证每次仓库合并后的自动同步。主要参考文件Registry 文档首页Getting Started、Upload 指南Registry CLI、Schemas、RulesGitHub Actions、GitLab CI/CDCLI 认证、Postman 转换包【免费下载链接】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：用 Git 深度集成为 OpenAPI 与 AsyncAPI 文档构建单一事实来源
Scalar Registry用 Git 深度集成为 OpenAPI 与 AsyncAPI 文档构建单一事实来源【免费下载链接】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/scalarScalar Registry 是 Scalar 开源 API 平台中的集中式 API 注册表用于存储、版本化并统一管理 OpenAPI/AsyncAPI 文档、JSON Schema 与 Spectral 规则。阅读本文可以完整掌握 Registry 的定位与核心能力并学会通过 Dashboard、CLI 以及 GitHub Actions / GitLab CI 把 API 文档发布、校验和治理流程接入团队现有的 Git 工作流使 API 文档、SDK 与自动化始终消费同一份来源。为什么需要 RegistryAPI 管理的复杂性会随着团队规模迅速膨胀真实来源在哪里、版本如何管理、谁有访问权限、下游消费者如何发现更新——这些问题没有统一答案时文档、SDK 和自动化脚本就会各自为政、逐渐失真。Registry 给团队提供了一个放置 OpenAPI 与 AsyncAPI 文档的中央位置以及围绕它们的全部工作流。正如文档首页 documentation/guides/registry/index.md 所述一旦 API 文档进入 Registry就可以从同一份来源驱动文档Docs、SDK 生成、发布和自动化无需在多处复制粘贴。六大核心能力原文档列出的六个功能点构成本篇后续所有实操章节的主线能力说明对应实操章节Single source of truth单一事实来源API 文档、Schema、规则集中存放在一个受管理的位置下文全部章节Git integrationGit 集成将 Registry 接入仓库工作流更新遵循团队既有的评审流程CI/CD 集成OpenAPI and AsyncAPI对 OpenAPI 与 AsyncAPI 文档做版本化并发布供文档、SDK 与自动化消费CLI 发布JSON Schema support把共享 Schema 与依赖它的 API 文档一起管理Schema 管理Spectral rules存放规则支撑一致的 API 治理与校验工作流规则与 LintPrivate or public控制 API 文档是内部使用、团队共享还是公开各资源的访问控制从 Registry 生成 API 文档与 SDKRegistry 是 Scalar 各产品之间的文档总线。在 Dashboard 上点击几次即可基于 Registry 中的文档生成 API 文档API References文档与 OpenAPI 变更保持连接更新直接从来源流向已发布的文档页面。基于同一份 OpenAPI 文档还能生成 SDK让客户端库始终与 API 变更保持一致——Registry 负责维护来源文档与生成工具之间的连接。生成 API 文档的完整流程见 API References 入门 与 Docs 入门生成 SDK 的完整流程见 SDK Generator 入门支持的事件驱动文档格式见 AsyncAPI 说明这种一份文档驱动一切的模式在仓库中也能找到直接证据README.md 中的示例演示了把 API Reference 的url直接指向 Registry 上的文档地址registry.scalar.com/scalar/apis/galaxy?formatjson即文档页面消费的是 Registry 中版本化的文档资源而非本地快照。快速开始创建账号与上传第一份文档Registry 属于 Scalar 托管产品需要先注册账号。流程如下详见 Getting Started 指南注册/登录 Scalar 账号Dashboard 位于dashboard.scalar.com。登录后可通过三种方式操作 RegistryDashboard网页端管理CLI终端与 CI 中程序化操作见 Registry CLI 指南GitHub Actions仓库自动化推送见 GitHub Actions 指南。通过 Dashboard 上传 API 文档上传操作的完整步骤来自 Upload 指南在 Dashboard 右侧面板点击Import API或进入侧边栏 Products 下的 Registry 页面点击Create new API可上传任意版本的 OpenAPI 或 AsyncAPI包括 Swagger 2.0甚至 Postman Collection。Postman 导入能力在仓库中对应开源的转换包 packages/postman-to-openapi其convert函数负责把 Postman 集合转为标准 OpenAPI 文档isPostmanCollection可用于判断输入是否为 Postman 集合上传成功后API 文档即位于你所在团队的命名空间namespace之下。更新与删除文档更新使用 Scalar 的 OpenAPI Editor或从 Registry 页面点击Edit Document编辑文档。完成编辑后点击右上角Publish即可向 Registryupsert 一个新版本——同一版本会被覆盖更新新版本会被追加删除可从 Registry 的 Overview 页面删除文档但文档明确提醒删除前要考虑下游影响因为 Docs、SDK、自动化都可能依赖该文档资源。通过 CLI 管理 RegistryCLI 是 Registry 面向终端与 CI 的接口。执行任何命令前需先通过 API key 完成 CLI 认证scalar auth login或scalar auth login --token token直接指定令牌。发布 API 文档scalar registry publishscalar registry publish ./openapi.yaml --namespace your-team --slug your-apipublish同时接受 OpenAPI 与 AsyncAPI 文档。文档格式在到达 Registry 时自动识别因此两类文档使用完全相同的命令scalar registry publish ./asyncapi.yaml --namespace your-team --slug your-events-api必填参数参数说明fileAPI 文档路径位置参数--namespace你的 Scalar 团队命名空间--slugRegistry 条目的唯一标识符未指定时默认取文档 title可选参数参数说明--versionAPI 版本号例如0.1.0--private将 API 设为私有默认false--force强制覆盖已存在的版本默认false示例# 基础发布 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文档管理list / update / delete# 查看团队名下所有 Registry API scalar registry list --namespace your-team # 只更新标题与描述无需重新上传文件 scalar registry update your-team your-api --title New Title --description New description # 从 Registry 删除文档 scalar registry delete your-team your-api发布前的校验与 Lint# 校验 OpenAPI 文档 scalar document validate ./openapi.yaml # 使用 Spectral 规则做 lint scalar document lint ./openapi.yaml # 使用 Registry 中存放的 Rules scalar document lint ./openapi.yaml --rule https://registry.scalar.com/your-team/rules/your-rule一个值得注意的行为差异原文档以 NOTE 形式强调scalar document lint支持 AsyncAPI——它会自动识别文档类型对 AsyncAPI 文档运行 Spectral 的spectral:asyncapi规则集而不是spectral:oas保证报告的问题确实适用于该文档而scalar document validate目前仅支持 OpenAPI指向 AsyncAPI 文档时会停止并提示改用lint。向 Registry 发布 AsyncAPI 文档不受影响一切照常。多团队与多 API 场景如果你属于多个团队可以切换当前激活的团队# 列出你所在的全部团队 scalar team list # 设置激活团队 scalar team set --team team-uid仓库中包含多个 API 时可以在脚本或 CI/CD 中批量发布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管理共享 JSON SchemaRegistry 中的 Schema 允许把独立的 JSON Schema 对象发布到 OpenAPI 文档之外。与内嵌在 OpenAPI 文档中的 Schema 不同Scalar Schemas 具备四个特征来自 Schemas 指南Standalone独立独立于任何特定 API 管理Reusable可复用可被 Registry 中多个 API 引用Versioned版本化每个 Schema 有独立于 API 的版本线Shareable可共享可公开共享也可在团队内保持私有。创建并配置 Schema在 Dashboard 左侧边栏 Registry Schemas 下点击 New创建。需要配置的元数据配置项说明Schema Name描述其用途的名称如 User Profile、Payment MethodDescription该 JSON Schema 定义了什么、应如何使用Version初始版本如0.1.0、1.0.0后续可随发布迭代Namespace发布到的团队命名空间决定引用该 Schema 的 Registry 路径Schema AccessPublic任何人可通过 Registry URL 引用Private仅受邀用户与 access group 可访问引用在Edit标签页的 Schema 编辑器中定义 JSON Schema 本体。文档给出的示例Draft 2020-12{ $schema: https://json-schema.org/draft/2020-12/schema, type: object, title: User Profile, description: A user profile schema with contact information, properties: { id: { type: string, format: uuid, description: Unique identifier for the user }, email: { type: string, format: email, description: Users email address }, name: { type: object, properties: { first: { type: string, minLength: 1 }, last: { type: string, minLength: 1 } }, required: [first, last] }, createdAt: { type: string, format: date-time } }, required: [id, email, name] }点击Publish后即可获得用于引用的 Registry 路径registry.scalar.com/your-team/schemas/your-schema-nameversion用 sha 精确钉住版本文档中任何可以写 version 的位置都可以改写 sha——既可以是文档内容 sha也可以是其来源的 Git commitregistry.scalar.com/your-team/schemas/your-schema-name03e959a解析规则与原文明确的约束sha 支持前缀6 到 64 个十六进制字符匹配方式类似 git前缀匹配到多个文档时返回 404 而不是猜测版本永远优先与既有版本匹配的值仍解析到该版本公开文档的完整 64 位内容 sha 是不可变的会以长生命周期缓存提供服务该寻址方式对 API 文档同样适用/your-team/apis/…sha。在 API 文档中引用 Schema发布后可在 OpenAPI 文档中用$ref引用实现同一 JSON Schema 定义跨多个 API 复用同命名空间内的相对引用components: schemas: User: $ref: your-team/schemas/user1.0.0跨命名空间或公共 Schema 的完整 URL 引用components: schemas: User: $ref: https://registry.scalar.com/other-namespace/schemas/user1.0.0完整示例——在 OpenAPI 文档中使用 Schemaopenapi: 3.1.0 info: title: User API version: 1.0.0 paths: /users: get: responses: 200: description: List of users content: application/json: schema: type: array items: $ref: your-team/schemas/user1.0.0用 CLI 管理 Schema# 认证二选一 scalar auth login scalar auth login --token your-api-token # 发布 Schema scalar schema publish ./schema.json --namespace your-team --name user --version 1.0.0 # 列出命名空间下的所有 Schema含版本与访问级别 scalar schema list --namespace your-team # 更新元数据无需重新上传文件 scalar schema update --namespace your-team --name user --description Updated user profile schema # 删除某个版本的 Schema scalar schema delete --namespace your-team --name user --version 1.0.0scalar schema publish的参数参数必填说明file是JSON Schema 文件路径--namespace是团队命名空间--name是Schema 名称标识--version否版本号未指定时默认为0.0.1--private否设为私有默认false--force否强制覆盖已有版本默认false注意删除某个 Schema 版本会打断所有 OpenAPI 文档中对它的引用删除前务必先更新全部引用。Schema 最佳实践原文档给出的工程实践建议版本化采用语义化版本破坏性变更升 major新增可选属性升 minor修正与澄清升 patchSchema 设计保持聚焦与可复用避免只能用于单一场景的过具体 Schema属性命名要有描述性并附description善用format、pattern、minLength等校验能力复杂嵌套结构用$defs组织访问控制跨团队/组织共享的数据模型用 public组织内部数据模型用 private同一数据的内部表示与对外表示考虑拆成不同 Schema组织方式全库命名规范一致用命名模式归类相关 Schema如user-*、payment-*、address-*并写清描述。用 Spectral 规则做 API 治理Registry 中的 Rules 用于以 Spectral 兼容的规则集对 OpenAPI 文档做 lint 与校验可跨托管的 API 与 Schema 使用。创建规则在 Dashboard 侧边栏 Rules 下点击 New创建。新建的规则默认继承 Spectral OSS 规则集extends: spectral:oas rules: {}这提供了 OpenAPI lint 的坚实基础并支持三种定制方式扩展其他规则集、添加自定义规则、覆盖既有规则。规则的访问控制与其他 Registry 资源一致规则分两档Public Rules任何人可通过 Registry 路径访问适合开源项目或与社区共享 lint 标准Private Rules限定在组织内部可共享给特定 access group适合内部 API 标准与公司级 lint 要求。访问控制在规则的 Overview 页面管理方式与其他 Registry 资源相同。用 CLI 应用规则# 默认 lint scalar document lint ./openapi.yaml # 使用 Registry 中的特定规则 scalar document lint ./openapi.yaml --rule https://registry.scalar.com/your-team/rules/your-rule # 使用本地规则文件 scalar document lint ./openapi.yaml --rule ./my-custom-ruleset.yamlGit 集成GitHub ActionsRegistry 的 Git 集成让文档更新遵循仓库既有的评审流程。完整参考见 GitHub Actions 指南。基础工作流验证并推送 OpenAPI 文档到 Registry# .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按环境部署针对 development/staging/production 多环境场景工作流可按分支切换命名空间main分支发布到SCALAR_NAMESPACE_PRODUCTIONdevelopment分支发布到SCALAR_NAMESPACE_DEVELOPMENT两个分支均通过paths: api/**/*.yaml触发。发布前先执行document validate认证则通过环境变量SCALAR_API_KEY完成scalar auth login。其他模式指南中还给出了两套可直接套用的模式Pull Request 校验在pull_request事件中对api/**路径变更运行npx scalar/cli document validate把校验前移到合并之前多 API 仓库用strategy.matrix并行处理多个 API示例矩阵覆盖user-api、product-api、order-api每个 API 独立执行校验 → 登录 → 发布namespace 由仓库变量SCALAR_NAMESPACE注入。SCALAR_API_KEY在 Dashboard 的user/api-keys页面获取并添加到 GitHub 仓库的 Secrets 中。Git 集成GitLab CI/CDGitLab 侧的等价方案见 GitLab CI/CD 指南。基础流水线stages: - validate - deploy validate_openapi: stage: validate image: node:20 script: - npx scalar/cli document validate api/openapi.json rules: - if: $CI_COMMIT_BRANCH $CI_DEFAULT_BRANCH push_to_scalar_registry: stage: deploy image: node:20 script: - npx scalar/cli auth login --token $SCALAR_API_KEY - npx scalar/cli registry publish --namespace your-team --slug your-api api/openapi.json rules: - if: $CI_COMMIT_BRANCH $CI_DEFAULT_BRANCH needs: - validate_openapi扩展模式按环境部署deploy_production默认分支触发environment: production与deploy_developmentdevelopment分支触发共用同一个validate_openapi校验阶段各自使用SCALAR_NAMESPACE_PRODUCTION/SCALAR_NAMESPACE_DEVELOPMENTMerge Request 校验在merge_request_event且api/**有变更时运行document validate在合并前拦截不合规文档多 API 仓库两种写法——用 YAML 锚点模板validate_template/deploy_template为每个 API 生成成对的 validate/deploy job或更简洁的parallel: matrix方案用一个validate_apis与一个deploy_apis并行 job 覆盖所有 API变量配置在项目的 Settings → CI/CD → Variables 中配置SCALAR_API_KEY建议 masked与SCALAR_NAMESPACE或分环境的SCALAR_NAMESPACE_PRODUCTION/SCALAR_NAMESPACE_DEVELOPMENT。小结Registry 的价值链条可以概括为来源OpenAPI/AsyncAPI 文档、独立 JSON Schema、Spectral 规则三类资源统一存放各自带版本与访问控制流转通过 Dashboard 的 Edit/Publishupsert 语义或 CLI 的publish/force参数控制版本演进通过 sha 钉住精确快照治理validate保证结构正确lint含 AsyncAPI 自动识别规则集保证风格一致消费API 文档、SDK 与下游自动化从同一份 Registry 来源取数Git 工作流GitHub Actions / GitLab CI保证每次仓库合并后的自动同步。主要参考文件Registry 文档首页Getting Started、Upload 指南Registry CLI、Schemas、RulesGitHub Actions、GitLab CI/CDCLI 认证、Postman 转换包【免费下载链接】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），仅供参考