最高の OpenAPI バリデーターツール：クリーンなAPI仕様のために

OpenAPI仕様は契約です。コードジェネレーターはこれを読み込み、ドキュメントはこれに基づいて構築され、モックサーバーはこれ上で動作し、クライアントSDKはこれによって生成されます。仕様が間違っていると、それらの下流の成果物すべてがエラーを継承します。バリデーターは、エラーが広がる前に、仕様ファイル内の問題を発見します。

このまとめでは、使用する価値のあるOpenAPIバリデーターツール、それぞれの得意なこと、そして実際のワークフローにどのように組み込むかについて説明します。一部は生の構文をチェックします。その他はスタイルと設計ルールを強制します。最適な設定は通常、両方を組み合わせたものであり、このガイドではその組み合わせ方を説明します。

なぜ仕様の検証が重要なのか

バリデーターが解決する問題には2つの明確な種類があり、これらを混同すると混乱が生じます。

1つ目は「正確性」です。そもそもファイルは有効なOpenAPIなのか？インデントが間違っているYAMLブロック、どこにもリンクしていない$ref、必須のdescriptionが欠落しているレスポンス、型名に誤字があるスキーマ。これらは客観的なエラーです。ファイルはOpenAPIスキーマに対して解析されるか、されないかのどちらかです。正確性バリデーターは、YesかNoかの答えを出します。

2つ目は「品質」です。仕様は有効だが、良いものか？すべての操作にはサマリーがあるべきです。パス名は一貫しているべきです。すべてのエラーレスポンスは文書化されているべきです。セキュリティは宣言されているべきです。これらはOpenAPIスキーマでは必須ではありませんが、これらをスキップすると、技術的には有効だが消費するのが困難な仕様が生まれます。リンターはこれらの設計ルールを強制します。これらの両方の問題のクラスを早期に発見することは、SDKが出荷された後に発見するよりもはるかに費用対効果が高く、これはより広範なAPI契約テストの背後にあるのと同じ論理です。

知っておくべきバリデーターツール

Swagger Editor

Swagger Editorは、OpenAPIプロジェクトの公式ブラウザベースエディターです。左側に仕様を貼り付けるか書き込み、右側で検証エラーとレンダリングされたプレビューをリアルタイムで確認できます。セットアップなしで、仕様が構文的に有効であるかを確認する最速の方法です。編集や簡単なチェックには優れていますが、自動化されたパイプライン実行にはあまり適していません。Swagger Editorは無料で、完全にブラウザで動作します。

Spectral

Stoplight社のSpectralは、ほとんどのチームが品質強制のために採用しているリンターです。OpenAPIとAsyncAPIのルールセットが付属しており、その真価はカスタムルールにあります。すべての操作に説明が必要であるとか、パスの末尾のスラッシュを禁止するといった独自の規約を強制するために、YAMLまたはJavaScriptでルールを記述します。コマンドラインから実行されるため、CIに自然に適合します。Spectralプロジェクトはオープンソースです。

openapi-spec-validator

openapi-spec-validatorは、OpenAPIバージョン2.0、3.0、3.1の公式OpenAPIスキーマに対して仕様をチェックするという1つの仕事をうまくこなす、Pythonに特化したツールです。スタイルに関する意見はなく、ファイルが構造的に正しいかどうかを伝えます。ライブラリとしてもCLIとしても、Pythonベースのビルドステップやプリコミットフックにきれいに組み込むことができます。厳格な合否判定の正確性ゲートが必要な場合、これはクリーンな選択肢です。

Apidog

Apidogは、統合された設計ワークフローの一部として仕様を検証します。OpenAPI定義を構築またはインポートすると、エディターで構造上の問題がフラグ付けされます。そのより特徴的な機能はランタイム検証です。ライブAPIレスポンスを仕様で宣言されたスキーマと照合し、実装が契約と一致しなくなった「ずれ」を検出します。これにより、有効なドキュメントと正しいAPIとの間のギャップが解消されます。Apidogをダウンロードして、1つのツールで仕様を設計し、検証してください。

Redocly CLI

Redocly CLIは、リンティング、検証、ドキュメント生成をバンドルしています。OpenAPIスキーマに対して検証し、設定可能なルールセットが付属しており、複数のファイルに分かれた仕様を1つのバンドルに解決できます。Redocで既にドキュメントをレンダリングしているチームは、別の依存関係を追加することなく、同じツールチェーンで検証を利用できます。

Vacuum

VacuumはGoで書かれた高速なOpenAPIリンターです。そのセールスポイントは、一部のJavaScriptベースのリンターが遅くなるような非常に大きな仕様での速度です。Spectralスタイルのルールと互換性があるため、チームはほとんど手直しなく切り替えることができます。広大なAPIサーフェスを持つモノレポでは、パフォーマンスの違いは顕著です。

比較表

検証ワークフローの構築方法

1つのツールを選ぶのではありません。それらを重ねて使用します。

まず、編集する場所から始めます。仕様を作成する際は、Swagger Editorや統合プラットフォームを使用して、入力時にエラーが表面化するようにします。これにより、明らかな間違いをすぐに捕捉でき、後で捕捉するよりもはるかに費用対効果が高くなります。

CIに正確性ゲートを追加します。仕様に触れるすべてのプルリクエストでopenapi-spec-validatorまたはそれに相当するCLIを実行します。ファイルがOpenAPIスキーマに対して検証されない場合、ビルドは失敗します。これは交渉の余地のない、二者択一の問題です。

その隣に品質ゲートを追加します。Spectral、または大規模な仕様の場合はVacuumを、チームが合意したルールセットで実行します。組み込みのOpenAPIルールから始め、次に独自の規約のためのカスタムルールを追加します。ルールセットはバージョン管理に含め、APIと共に進化するようにします。これは、CI/CDでのテスト自動化を信頼できるものにするのと同じ規律です。つまり、誰かが覚えていなくても、チェックは毎回実行されます。

最後に、実行中のAPIを仕様に対して検証します。仕様が完璧でも、実装がそれから乖離している場合があります。Apidogを介したランタイム検証、またはスイート内の契約テストにより、APIがまだその契約と一致していることを確認します。テスト側については、有用なAPIアサーションの記述で、文書化されたスキーマに対してレスポンスをチェックする方法を説明しています。

よくある間違い：一度だけ検証する

多くのチームは、仕様を最初に作成したときに一度だけ検証し、その後は二度と行いません。そこから仕様は腐敗していきます。開発者がコードにエンドポイントを追加し、仕様を忘れます。誰かがレスポンスの形状を微調整します。6か月後、仕様はもはや存在しないAPIを記述し、生成されたSDKやドキュメントは静かに間違っています。

検証は継続的である必要があります。CIに組み込み、仕様へのすべての変更がチェックされ、APIへのすべての変更が仕様に対してチェックされるようにします。仕様の失敗は、失敗する単体テストと同じように扱います。つまり、ビルドはパスしません。この原則は、一般的な自動テストの背後にあるものと同じで、チェックは誰かが実行しようと決めなくても実行される場合にのみ価値があります。

また、適切なOpenAPIバージョンに対して検証することも役立ちます。3.1リリースではOpenAPIがJSON Schemaに整合され、一部のスキーマ構造の動作が変更されました。ツールが3.0を想定しているのに、仕様が3.1を宣言している場合、誤解を招く結果が得られる可能性があります。公式のOpenAPI Specificationにはバージョン間の違いが文書化されており、ほとんどのバリデーターではバージョンを明示的に指定できます。

バリデーターが発見し、見落としがちなこと

「仕様が間違っている」というのは行動するには曖昧すぎるため、検証が表面化する問題の種類について具体的に説明する価値があります。

構造エラーは最も想像しやすいものです。存在しないスキーマを指す$ref。OpenAPIが要求するdescriptionがないレスポンスオブジェクト。URLテンプレートで宣言されているがparametersリストで定義されていないパスパラメータ。例では文字列を示しているのにtype: integerと記述されているスキーマ。正確性バリデーターはこれらすべてにフラグを立てます。これらがなければ、コードジェネレーターを壊したり、壊れたSDKを生成したりするでしょう。

品質の問題はより微妙で一般的です。operationIdがない操作は、生成されたクライアントメソッド名を醜くしたり不安定にしたりします。パスの大文字小文字の不一貫性（一部のルートではsnake_caseを使用し、他のルートではcamelCaseを使用）。200レスポンスは文書化されているが、400や401は文書化されていないエンドポイント。これにより、コンシューマーはエラーがどのように見えるかを知りません。APIが実際に必須としているのに、リクエストボディがオプションとマークされている場合。これらはどれもパーサーを壊しませんが、すべてAPIを使いにくくし、リンターがこれを防ぐ役割を果たします。実際の動作との関連性は、仕様自体がクリーンになった後にAPI契約テストが検証するものです。

デザインファーストワークフローへの検証の組み込み

多くのチームは現在、コードを書く前にAPIを設計し、最初にOpenAPI仕様を作成し、そこからサーバーのスタブ、モック、ドキュメントを生成しています。検証は、このモデルではさらに重要になります。なぜなら、仕様は既存のAPIのドキュメントではなく、すべてが構築される情報源だからです。仕様の欠陥は、生成されたサーバーの欠陥となります。

デザインファーストのフローでは、設計の瞬間に検証を行います。エディターレベルのチェックは、コード生成が実行される前に、仕様が形になる段階で間違いを捕捉します。次に、CIゲートが何も退行していないことを確認します。仕様がモックサーバーも駆動するため、クリーンな仕様はモックが正しく動作することを意味し、フロントエンドチームとクライアントチームが信頼できる代替物に対して構築できます。仕様がモックにどのように供給されるかを知りたい場合は、テストのためのAPIモックに関するガイドがその関連性を示しています。この規律はそれ自体が報われます。仕様を有効に保つために費やされた1時間は、後にクライアントの不一致をデバッグする数時間を節約します。

よくある質問

OpenAPIバリデーターとリンターの違いは何ですか？

バリデーターは、仕様がOpenAPIスキーマに対して構造的に正しいかどうかをチェックし、合否判定を出します。リンターは、すべての操作に説明があるか、パスの命名が一貫しているかなど、品質とスタイルをチェックします。多くのツールは両方を行いますが、異なる質問に答えるものであり、強力なワークフローでは両方を使用します。

OpenAPI仕様を無料で検証できますか？

はい。Swagger Editor、Spectral、openapi-spec-validator、Redocly CLI、Vacuumはすべて無料でオープンソースです。Apidogは無料枠で仕様を検証し、ランタイムチェックを追加します。費用を理由に検証をスキップする理由は何もありません。

OpenAPI 3.0と3.1は異なる方法で検証すべきですか？

同じツールで検証しますが、バージョンを固定する必要があります。OpenAPI 3.1はJSON Schemaと整合され、一部のスキーマ動作が変更されたため、3.0を想定しているバリデーターは、3.1仕様で誤ったエラーを報告する可能性があります。ツールが仕様が宣言するバージョンをサポートしていることを確認してください。

仕様の検証はどこで実行すべきですか？

2つの場所で実行します。1つは仕様を作成する際にエディターでリアルタイムに実行し、間違いがすぐに表面化するようにすること。もう1つは、すべてのプルリクエストでCI内で実行し、壊れた仕様や品質の低い仕様がマージされないようにすることです。エディターのみの検証はスキップされがちですが、CIでの検証はそうではありません。

APIが仕様と一致していることをどのように確認しますか？

仕様の検証はドキュメントが正しいことを確認するだけであり、実装がそれに一致していることは確認しません。ずれを検出するには、ライブAPIレスポンスを仕様内のスキーマと比較する契約テストまたはランタイム検証を実行します。Apidogはこれを直接行い、契約テストフレームワークはテストスイートで行います。