schemaguard

SchemGuard

API スキーマのドリフト監視 — OpenAPI 仕様の破壊的変更を、利用側に影響が出る前に検出します。

理由

API は気づかないうちに壊れます。フィールド名が変更されたり、エンドポイントが削除されたり、列挙型の値がなくなったりすると、本番環境で下流の利用側に影響が及びます。SchemGuard は、デプロイ前にこれらを検出します。

インストール

npm install -g schemaguard

使用方法

2 つの仕様を比較する

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

エージェントや CI ツールがプログラムから利用できる、構造化された JSON を返します。

検出項目

破壊的変更（終了コード 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

プログラム API

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