OpenAPI スペックの検証 クライアントが破損する前に、Swagger ファイル内のエラーをキャッチする

OpenAPI スペックは、API とその消費側（自動生成されたクライアント、モックサーバー、ドキュメント、テストフレームワークなど）の間の契約です。問題は、アプリケーションコードとは異なり、破損したスペックは例外を投げません。静かに誤った出力が下流に生成され、最初に気づくのは、クライアント SDK が使用できないコードを生成したり、ドキュメントがエンドポイントを欠落している場合です。

スペックエラーを消費者に届けられる前に早期にキャッチすることは、スペック検証の役割です。この記事では、検証すべき内容、よく発生するエラーの場所、およびローカルおよびブラウザ内で検証する方法について説明します。

あなたのスペックフォーマットがドキュメントにとどまらない理由

多くの開発者は、OpenAPI スペックをドキュメントアーティファクトと考えています — それは Swagger UI または Redoc を駆動するものだと考えています。これは半分の話です。スペックは、以下のすべての場面で「真実の源」として機能します：

• コード生成 — openapi-generator または swagger-codegen などのツールは、スペックからサーバースタブおよびクライアントライブラリを直接生成します。不正なスキーマは不正なコードを生成します。
• 契約テスト — Dredd または Schemathesis などのフレームワークは、実際のAPIをそのスペックと比較してテストします。不正なスペックはテストが実行されないか、誤った結果を生成します。
• モックサーバー — Prism などのツールは、スペックの例値およびスキーマに基づいてモック応答を提供します。不正なスキーマは不正なモックを生成します。
• ゲートウェイ設定 — AWS API Gateway、Kong などは、OpenAPI スペックをインポートしてルーティング、認証、検証を設定できます。不正なスペックは静かにルートを削除または誤った設定を引き起こします。

これらのツールのいずれも、スペックが間違っていることを人間が読み取るようではありません。それらはクラッシュしたり、ゴミを生成したり、影響を受けた部分を静かにスキップします。スペックがこれらの消費者に届ける前に検証することは、絶対に必要です。

OpenAPI 2.0 と 3.0 と 3.1：人々が誤りを犯すバージョンの違い

スペックのトップに宣言されたバージョンは、適用されるルールを変えるため、多くのエラーはバージョン間の慣例の混同から生じます。

• OpenAPI 2.0（Swagger） — 使います swagger: "2.0". リクエストボディは parameters は迅速なパスだが、属性の扱いが不一致であり、エッジケースでデータを失う可能性がある。SOAPレスポンスのプロダクション用途では、 in: body. 定義は definitions、ではなく components/schemas. スキーマレベルでのサポートなし oneOf, anyOf、 または not です。
• OpenAPI 3.0.x — 使います openapi: "3.0.x". リクエストボディは requestBody. スキーマは components. 支持 oneOf, anyOf, allOfと、 not. 追加 links と callbacks.
• OpenAPI 3.1.0 — JSON Schema Draft 2020-12 と完全に一致します。 nullable は type: [string, null]. exclusiveMinimum/exclusiveMaximum から数値に変更されます。 $schema はスキーマに許容されます。

最も一般的な移行エラー：2.0 スペックをコピーし、バージョンフィールドを 3.0.0 に変更するだけですが、リクエストボディを parameters に requestBodyから移動していないこと。スペックはJSON/YAMLとして有効ですが、意味検証では失敗します。

よく見られるスペックエラーとその隠れ場所

スペックエラーは予測可能なパターンに従います。以下は、実際のコードベースで最もよく見られるものです：

必須フィールドの欠如

すべての操作には少なくとも1つの2xx応答が定義されなければなりません。すべてのパラメータには name および in の値が必要です。URLに宣言されたパスパラメータ（例： /users/{id}）には、対応するパラメータオブジェクトが必要です。 in: path と required: trueこれらを欠落させると、パーサーが解析可能なスペックとなりますが、検証ツールやコード生成ツールが破損します。

無効な $ref パス

あ $ref が存在しないコンポーネントを指すのは、最も一般的なスペックバグです。参照は形式的に有効に見えますが、ターゲットスキーマがリネームまたは削除されたためです。JSON/YAML パーサーはこれを無視し、スペックに問題があることを検出するだけの検証ツールがそれをキャッチします。 $ref: "#/components/schemas/UserProfile" 外部

パスはさらに危険です — 他のファイルやURLを指すため、すべての環境でアクセスできない可能性があります。スペックを配布する前に、その参照をインラインにしますか、または外部を解決しないツールで使用する場合は、参照をインラインにします。 $ref 不正なスキーマタイプ

スキーマタイプの不一致は微妙です。浮動小数点値を返すフィールドに

を宣言する。Unix タイムスタンプ（整数）を返すフィールドに type: integer を使用する。宣言された format: date-time に一致しない値を持つ enum を定義する。これらはYAMLパーサーを通過するが、生成されたクライアントに誤ったプロパティを生成します。 type循環参照

スキーマが自らを参照する — 直接または

値の連鎖を通じて — は、コード生成ツールやドキュメントツールが無限ループまたはクラッシュを引き起こします。ほとんどの検証ツールは循環参照を検出し、報告しますが、深くネストされたスキーマでは取り除くのが難しい場合があります。解決策は、再帰的なケースに専用のスキーマを用意することです。 $ref 構造的エラーと意味的エラー

検証エラーはすべて同じではありません。その違いを理解することは、問題の優先順位を決定するのに役立ちます：

構造的エラー

• — スペックがOpenAPIスキーマに準拠していない。必須フィールドが欠落、プロパティ名が間違っている、またはタイプがスキーマ形式と一致していない。これらは厳密なスキーマ検証によって検出され、ほとんどのツールをブロックします。 意味的エラー
• — スペックが構造的に有効なJSON/YAMLであり、スキーマ検証を通過しているが、実際には機能しない内容を記述している。URLにパスパラメータがあるが、パラメータ定義がないエンドポイント。応答スキーマが と競合する必須フィールドを使用している。これらは基本的なスキーマチェックではなく、より深いルーニングルールによって検出されます。 allOf ほとんどのオンライン検証ツールおよび基本的なCLIツールは構造的エラーを検出します。意味的エラーを検出するには、Spectralのようなルールベースのリントツールが必要です。これはスペックの内部論理と一貫性を評価します。

components/schemas: DRY定義とインラインスキーマ

OpenAPI 3.0 では

が再利用可能なスキーマを定義する標準的な場所として導入されました。トレードオフは次の通りです： components/schemas components に共有されるスキーマ

• — 複数の場所で同じスキーマが現れる場合（例：複数のエンドポイントから返される オブジェクト）に正確です。 User を使用することで、スペックをDRY（Dont Repeat Yourself）に保ち、クライアントSDKに1つの名前付きクラスを生成します。 $ref: "#/components/schemas/User" インラインスキーマ
• — 1つのエンドポイントに特化した一時的な応答形状に適しています。インラインは、 に一度限りの定義を汚染し、スペックを読みにくくするのを防ぎます。 components/schemas 反パターンは、

にスキーマを定義し、それらを参照しないことです。Spectralなどの検証ツールは未使用コンポーネントをフラグにできます。これは、意図して参照すべきだったが、どこか別の場所を指している components/schemas の可能性を示唆します。 $ref requestBody と parameters：どこで誤りが起きるか

OpenAPI 3.0 では、リクエストボディとパラメータは厳密に分離されています：

parameters

• — パス、クエリ、ヘッダー、クッキー値に適用されます。各パラメータはスカラー値であり、複雑なオブジェクトではありません。 requestBody
• — リクエストペイロード（JSONボディ、フォームデータ、ファイルアップロード）に適用されます。POST/PUT/PATCH操作にボディを必要とします。 Swagger 2.0 から移行する開発者が犯す誤りは、リクエストボディがパラメータとして

だったことです。OpenAPI 3.0 ではそれが無効です — in: bodyは存在しません。リクエストボディが in: body を含むスペックはYAMLパーサーを通過しますが、スペック検証では失敗し、コード生成ツールはエラーを出したり、リクエストボディを静かに無視します。 in: body ローカルでスペックを検証する方法

ローカル検証に適した3つのCLIツール、最も簡単から最も徹底まで：

swagger-cli

高速な構造検証および

解決。簡易なチェックに適しています： $ref 構造エラーおよび破損した

npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yaml

パスを報告します。意味問題やスタイル問題は検出しません。 $ref Redocly CLI

構造検証に加えて、カスタマイズ可能なルールセット。生産スペックのデフォルトの厳密性に適しています：

欠落した説明、破損した参照、多くの意味問題を即座に検出します。

npm install -g @redocly/cli
redocly lint openapi.yaml

Spectral

最もカスタマイズ可能なリントツール。組み込みのOpenAPIルールセットおよびユーザーが定義したカスタムルールを実行します。スタイルガイドを内部で強制したいチームに最適です：

Spectralはエラー（スペックを破壊する）と警告（スタイルや完全性の問題）を区別しており、ブロッキング問題を最初に修正できるようにし、アドバイスルールのノイズを排除します。

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

ブラウザで何もインストールせずに検証する方法

スペックを迅速に検証したい場合（CLIやビルドを設定せずに）、

OpenAPI / Swagger スペック検証器（iotools.cloud） はブラウザ内で完全に動作します。YAMLまたはJSONスペックを貼り付けて、構造エラー、破損した パス、必須フィールドの欠如、OpenAPI 2.0、3.0、3.1のバージョンごとの問題を報告します。 $ref これは、コミット前にチェックする、誰かが送ったスペックを確認する、または注釈から生成されたスペックをコード生成前に sanity-check する際に役立ちます。

ワークフローに検証を組み込む

一時的な検証は即時問題を解決しますが、再発を防ぐことはできません。より持続可能なアプローチは次の通りです：

プレコミットフック

• — 各コミット前に実行します。破損したスペックはリポジトリに到達しません。 CIパイプラインステップ swagger-cli validate または spectral lint — 生成やデプロイに依存するスペック検証を、CIパイプラインの早期に追加します。
• 生成されたスペック検証 — コード注釈からスペックを生成（例：springdoc、swagger-annotations、FastAPI）する場合、生成された出力を検証し、注釈だけを検証するのではなくします。生成ステップ自体は注釈が衝突または不完全な場合に無効な出力を生成します。
• 目標は、無効なスペックを送信させないこと — ただ、消費者が問題を報告したときに修正するものではなく、それらを防ぐことです。 OpenAPI スペック検証：クライアントが破損する前に、Swagger ファイル内のエラーをキャッチする 2

OpenAPI スペック検証：クライア及が破損する前に、Swagger ファイル内のエラーをキャッチする 1

あなたも好きかもしれません