schemaguard

SchemGuard

API 架构漂移监控器——在 OpenAPI 规范中的破坏性变更影响使用方之前将其检测出来。

为什么需要

API 会悄无声息地发生破坏。字段被重命名、端点被移除、枚举值消失——下游使用方就会在生产环境中出错。SchemGuard 会在部署前发现这些问题。

安装

npm install -g schemaguard

使用方法

对比两个规范

schemaguard diff old-api.yaml new-api.yaml

输出：

Found 11 change(s):

❌ BREAKING CHANGES (9):
──────────────────────────────────────────────────
  ⛔ [endpoint-removed]
     Endpoint removed: DELETE /pets/{petId}
     at: DELETE /pets/{petId}

  ⛔ [field-type-changed]
     Parameter type changed: petId (string → integer)
     at: GET /pets/{petId} > param petId
  ...

🚨 9 breaking change(s) detected — deployment blocked.

CI 模式

schemaguard ci --spec ./openapi.yaml --baseline ./main-openapi.yaml

• 退出码为 0 = 没有破坏性变更，可以安全部署
• 退出码为 1 = 检测到破坏性变更，阻止流水线
• 退出码为 2 = 出错（规范无效、找不到文件）

检查规范

schemaguard lint ./openapi.yaml

检查是否缺少 operationId、描述、安全方案等。

JSON 输出

schemaguard diff old.yaml new.yaml --format json

返回结构化 JSON，供 Agent 和 CI 工具以编程方式使用。

检测内容

破坏性变更（退出码为 1）

规则	描述
endpoint-removed	端点已删除
method-removed	路径中的 HTTP 方法已移除
required-param-added	新增了必需参数
param-removed	已移除现有参数
request-field-made-required	请求字段变为必需字段
field-type-changed	字段类型已更改
response-field-removed	响应字段已移除
enum-value-removed	枚举值范围已缩小
auth-requirement-changed	安全方案已修改
response-code-removed	响应状态码已移除

非破坏性变更（仅提供信息）

规则	描述
endpoint-added	新增了端点
optional-param-added	新增了可选参数
response-field-added	新增了响应字段
enum-value-added	枚举值范围已扩大
description-changed	描述或摘要文本已更改
deprecated	端点已标记为弃用

GitHub Actions

- name: Check API compatibility
  run: npx schemaguard ci --spec ./openapi.yaml --baseline ./baseline.yaml

编程接口

import { parseSpec, diffSpecs, formatDiff } from 'schemaguard';

const oldSpec = parseSpec('./v1.yaml');
const newSpec = parseSpec('./v2.yaml');
const result = diffSpecs(oldSpec, newSpec);

if (result.hasBreakingChanges) {
  console.log(`${result.breaking.length} breaking changes found`);
}

许可证

MIT