openapi-parser

OpenAPI パーサースキル

参照ファイル

• references/schema-patterns.md — あらゆる複雑なパターン （anyOf / oneOf / allOf / discriminator / $ref / enum / pattern / nullable / optional）の解釈方法と列挙方法を、 snyk、digitalocean、posthog、front/core の仕様書にある実例とともに説明します。
• references/drift-mapping.md — 列挙したスキーマバリアントを Drift YAML にマッピングする方法を説明します。 データセット、式、ステートフルなケースのライフサイクルフック、各パターンタイプに対応する レスポンスマッチャーも含まれます。

ワークフロー

OpenAPI バージョン： このスキルは OpenAPI 3.x を対象としています。Swagger 2.0 の仕様書でも同じ構造パターン（$ref、allOf、oneOf）が使われますが、エンベロープ構文が異なるため、フィールド名を手動で調整する必要がある場合があります。 konfig-sdks/openapi-examples コレクションを使用する場合は、ナビゲーション用コマンドについて references/example-repos.md を参照してください。

1. エンドポイントを特定する

必要なものだけを抽出します。

# Find the line number of the endpoint (macOS/Linux/Git Bash/WSL)
grep -n "^  /path/to/endpoint" spec.yaml

# Read just that block (adjust line range as needed)
# Then follow each $ref to components/schemas
grep -n "SchemaName:" spec.yaml

# PowerShell equivalents (Windows)
Select-String -Path spec.yaml -Pattern "^  /path/to/endpoint" | Select-Object LineNumber, Line
Select-String -Path spec.yaml -Pattern "SchemaName:" | Select-Object LineNumber, Line

抽出するもの：パス／クエリ／ヘッダーパラメーター、リクエストボディのスキーマ、各レスポンスステータスコードのスキーマ。

2. $refs を再帰的に解決する

1. 仕様書内を Foo: で grep し、定義ブロックを見つけます。
2. Foo 自体に refs が含まれている場合は、それらも解決します。
3. プリミティブ型（string、integer、boolean、array、object）に到達したら終了します。

allOf: [$ref: Base, properties: {...}] は継承です。Base のフィールドとローカルの プロパティをマージして、完全なスキーマを取得します。すべてのパターンについては references/schema-patterns.md を参照してください。

3. 有効な組み合わせを列挙する

各レスポンスステータスコードについて、構造的に異なるスキーマバリアントを列挙します。スキーマのカバレッジを最大化する最小限のテストを目指し、オプションフィールドの組み合わせを際限なく増やさないようにします。

パターン	生成するテスト
oneOf / anyOf に N 個の分岐がある場合	N 個のテスト — 分岐ごとに 1 つ
N 個のマッピング値を持つ discriminator	N 個のテスト — discriminator の値ごとに 1 つ
allOf（合成／継承）	1 個のテスト — すべてのスキーマを 1 つのペイロードにマージ
enum	1 個のテストでカバーします。値が動作を左右する場合に限り、境界値のバリアントを追加します
オプションフィールドのまとまり	2 個のテスト：すべてのオプションフィールドを含むものと、含まないもの
nullable フィールド	正常系でカバーします。動作が変わる場合に限り、null のバリアントを追加します
pattern（正規表現）	パターンに一致する有効な例を 1 つ、ネガティブテスト用の無効な例を 1 つ

4. Drift テストケースを生成する

各組み合わせについて、Drift の操作ブロックを生成します。詳しいパターンは references/drift-mapping.md を参照してください。 主な規約：

• 操作には {operationId}_{variant} という名前を付けます（例：getImage_byId、getImage_bySlug）。
• 識別子付きユニオンでは、リクエストボディに識別子プロパティを明示的に設定します。
• anyOf のパスパラメーターでは、型バリアントごとに 1 つのテストを記述します。
• テストデータには dataset を使います。インラインの parameters は、静的でバリアントのない値（例：type: user のような固定の enum クエリパラメーター）に限って使用します。
• 401 テストでは、exclude: [auth] でグローバル認証を除外し、無効な bearer token を明示的に渡します。
• 意図的に無効なリクエストボディを送信する操作には、ignore: { schema: true } を追加します。
• 各テストには、対象とするスキーマ分岐を示すタグを付けます。
• expected から body を省略すると、Drift は OpenAPI スキーマに照らしてレスポンスを自動的に検証します。特定のフィールド値を検証する場合（例：識別子プロパティが正しく返された場合）に限り、明示的な body マッチャーを追加します。

5. 出力形式

常に次の内容を出力してください。

1. 分析 — ステータスコードの数、ポリモーフィックなスキーマ、生成されるテストの数とその理由
2. Drift オペレーション YAML — そのまま貼り付けられる完全な operations: ブロック
3. データセット YAML（必要な場合）— 参照されているテストデータ用の datasets: ブロック
4. 不足点 — 意図的に除外したスキーマの組み合わせとその理由

例

image_id: anyOf: [integer, string] の GET /v2/images/{image_id} の場合：

operations:
  getImage_byId:
    target: source-oas:getImage
    tags: [images, param-integer]
    parameters:
      path:
        image_id: ${image-data:images.existing.id}
    expected:
      response:
        statusCode: 200

  getImage_bySlug:
    target: source-oas:getImage
    tags: [images, param-string]
    parameters:
      path:
        image_id: ${image-data:images.existing.slug}
    expected:
      response:
        statusCode: 200

  getImage_notFound:
    target: source-oas:getImage
    parameters:
      path:
        image_id: ${image-data:notIn(images.*.id)}
    expected:
      response:
        statusCode: 404