このページは DevUtilities でブラウザ内の OpenAPI / Swagger ドキュメントを lint するための正式ガイドです。読みながら上に仕様を貼るか、下のトピックへジャンプしてください。検証はローカルに留まり、ドキュメントはアップロードされません。lint が緑になったら Kiota SDK Engine にパイプして準備スコアと generate コマンドのプレビューを確認します。

OpenAPI Validator は OpenAPI 3 と Swagger 2 の JSON/YAML 向けクライアント側リンターです。VALID、VALID WITH WARNINGS、INVALID をパス付き診断とともに報告し、SDK 生成やゲートウェイ取り込み前にブロッカーを直せます。

得られるもの

• OpenAPI 3.x と Swagger 2 ドキュメント（JSON または YAML）を解析
• ステータスバナー: VALID / VALID WITH WARNINGS / INVALID
• バージョンキー、paths カバレッジ、servers、よくある構造問題を検査
• ローカル限定 lint — 社内 API 仕様にも安全
• codegen 準備のための Kiota SDK Engine への直接引き渡し

次のときに使う

• Microsoft Kiota や他ジェネレーター前の高速プリフライトが必要
• CI や PR チェックリストがコミット済み仕様の読みやすい lint を要求
• Swagger 2 ファイルを継承し、OpenAPI 3 作業前に移行警告が欲しい
• 重複 operationId や壊れた $ref が codegen を壊し続けている

次のときは関連ツールを優先

• 完全な Kiota 準備スコア、言語マトリクス、CLI ビルダーが必要 → Kiota SDK Engine
• JSON ペイロードの整形だけが必要 → JSON Formatter
• モック応答配列が必要 → JSON Generator

コードジェネレーター（特に Kiota）は、ざっと YAML を見ただけでは見逃す構造問題で大きく失敗します。まずここで lint し、次に Kiota SDK Engine でジェネレーター固有の準備を確認します。

codegen 前に解消すべきブロッカー

• 重複または欠落した operationId（メソッド名の衝突）
• 成功ステータスの欠落または空の responses
• components への無効または宙ぶらりんな $ref
• openapi/swagger バージョンキー欠落、または空の paths オブジェクト
• 循環 schema 参照（多くは次に Kiota で表面化）

後回しにできる警告

• servers[] 欠落 — クライアントに --base-url 上書きが必要な場合あり
• Swagger 2 移行ノート — 新規 API では OpenAPI 3 を推奨
• 説明が薄い — ドキュメント品質であり、解析ブロッカーではない

SDK 生成前の初回ウォークスルー。

1. 入力パネルに OpenAPI 3 または Swagger 2 を JSON / YAML で貼り付けます。
2. ステータスを確認: VALID、VALID WITH WARNINGS、INVALID。
3. 診断リストのエラーをすべて修正 — operationId、responses、$ref 失敗から着手。
4. VALID になるか、許容できる警告だけになるまで再 lint。
5. クリーンな仕様を Kiota SDK Engine にパイプし、スコア・言語プレビュー・kiota generate コマンドを確認。
6. 修正したドキュメントをコミットし、任意でこの lint を PR チェックリスト項目に追加。

プルリクエストが OpenAPI 編集をマージし、後で夜間 SDK 再生成を壊します。レビュアーは重複 operationId を目視では見つけられません。

このツールによる解決方法

1. レビュー中に PR の OpenAPI ドキュメントをバリデーターに貼り付けます。
2. 承認前に VALID（または文書化された警告のみ）を要求します。
3. 診断テキスト付きで重複 operationId と壊れた $ref をレビュースレッドで指摘します。
4. マージ後、同じドキュメントに対して CI で Kiota を実行します。

ジェネレーターがぶつかるのと同じ失敗クラスを捉える、人間速度の lint ゲート — 仕様はアップロードしません。

チームが kiota generate を実行しようとしており、命名や $ref の問題で失敗しない確信が欲しい状況です。

このツールによる解決方法

1. INVALID がなくなるまでここで lint します。
2. Kiota SDK Engine にパイプし、OpenAPI Readiness スコアを確認します。
3. 残る Kiota 固有の問題（循環参照、nullable スタイル）を Kiota 診断で修正します。
4. 準備が十分になったら生成された CLI コマンドをコピーします。

ローカル二段階フロー: 構造 lint → Kiota 準備 → 手元で generate。

古い Swagger 2 JSON がまだゲートウェイを動かしています。関係者は Kiota 採用前に OpenAPI 3 を求めています。

このツールによる解決方法

1. Swagger 2 ドキュメントを貼り付け、移行警告を確認します。
2. どのコンバーターも阻む INVALID 構造問題を修正します。
3. 新機能向けに OpenAPI 3 移行を計画し、ゲートされている間だけ Swagger 2 を維持します。
4. Kiota 前に OpenAPI 3 結果を再 lint します。

Swagger 2 は警告付きで解析されるという明確な信号 — 新規 SDK 作業では OpenAPI 3 を推奨。

ジェネレーターは operationId からクライアントメソッド名を付けます。重複は衝突を起こします。

原因

2 つ以上のオペレーションが同じ operationId を共有しているか、ジェネレーターが要求する場所で operationId が欠落しています。

診断

ドキュメント内の繰り返された operationId を検索します。Kiota とこのリンターの両方が衝突をフラグします — SDK エンジンを開く前にここで修正してください。

修正

1. すべてのオペレーションに一意の operationId を割り当てます（動詞 + リソースがよくあるパターン）。
2. 編集中にコピーされた未使用の重複 paths を削除します。
3. 部分 SDK 用に削る場合は、本番 ID を安易に改名せず競合 paths を落とします。

改名後は再 lint し、Kiota 準備を再確認してください — プレビューのメソッド名が変わります。

使える responses がないオペレーションは型付きクライアント生成を壊します。

原因

path オペレーションが responses を省略しているか、成功 responses が schema なしの空 content {} になっています。

診断

各オペレーションの responses マップで 200/201（または default）を確認し、content schema が解決することを確かめます。

修正

1. application/json（または適切な）メディアタイプ付きの成功 response を少なくとも 1 つ追加します。
2. content を空のままにせず、$ref で components.schemas を指します。
3. クライアントが扱う必要がある場合はエラー responses（4xx/5xx）を文書化 — 省略すると警告が残ることがあります。

無効な $ref ポインターは lint と codegen 中の schema 解決を妨げます。

原因

$ref が欠落コンポーネントを指す、誤った JSON Pointer を使う、またはリゾルバーが展開できないサイクルを形成しています。

診断

失敗している各 $ref パスを components.schemas / parameters / responses までたどり、対象キーが存在し表記が一致することを確認します。

修正

1. 欠落コンポーネントの対象を修復または再作成します。
2. $ref 文字列を #/components/... ポインターに正規化します。
3. 浅い DTO を抽出して循環参照を断ちます（次に Kiota の循環参照ガイドが適用されます）。

ドキュメントを変更する前にバナーを解釈します。

OpenAPI Validator と Kiota SDK Engine は補完関係です。ここでは構造の健全性を lint し、Kiota でジェネレーター準備・言語マトリクス・エンドポイント選択・CLI コマンド書き出しを行います。

• VALID の後、クリーンな仕様を Kiota SDK Engine にパイプまたは貼り付けます。
• 重複 operationId、循環 $ref、nullable スタイルなどジェネレーターが重視する問題は Kiota 診断を使います。
• Kiota Generate ステップから kiota generate をコピー — ファイル出力は引き続きローカル Kiota CLI で実行されます。
• 両ツールをクライアント側に保ち、社内 API 契約がブラウザを離れないようにします。

• 承認前にすべての OpenAPI PR で lint します。
• 新規 API は OpenAPI 3 を優先し、Swagger 2 は移行警告付きのレガシーとして扱います。
• operationId を一意かつ安定に保つ — 改名は生成クライアントを揺らします。
• 成功 responses には常に解決可能な schema を与えます。
• Kiota を開く前に INVALID を解消し、次にジェネレーター固有の準備は Kiota で。
• このローカル経路で足りるなら、社内仕様を第三者 lint SaaS にアップロードしない。