この OpenAPI ビューア兼バリデーターは、YAML または JSON の OpenAPI 3.0・3.1、Swagger 2.0 ドキュメントを読み込み、閲覧しやすい API ドキュメントとして表示します。すべてのエンドポイントをタグ別にまとめ、パラメーター、リクエストボディ、レスポンス、スキーマに加えて、すぐに実行できる cURL コマンドも示します。仕様書を貼り付けるかファイルを開くだけで、アップロードは一切ないため、社内向けや未公開の API も外部に漏れません。
バリデーターは仕様から取り出した 23 の構造チェックを実行し、その一覧はページに記載しています。info と paths があること、レスポンスに description と有効なステータスコードがあること、パス内のすべての {parameter} が必須のパスパラメーターとして宣言されていること、operationId が一意であること、$ref が解決できること、セキュリティ要件が定義済みのスキームを指していることなどです。これらはコードジェネレーターやドキュメントツールを壊すエラーです。仕様の公式 JSON Schema に対する完全な検証ではないため、ここで合格した仕様書にも、たとえばスキーマのキーワードのつづり間違いが残っている可能性があります。他のファイルへの外部 $ref は一覧表示しますが、取得はしません。
使い方
- openapi.yaml、openapi.json、swagger.json を貼り付けるか、ファイルを開きます。最初はサンプルの API が読み込まれています。
- ステータス行と「検証」の一覧を確認します。各問題にはルールと場所(例:paths./pets/{id}.get)が示されます。
- ドキュメントを閲覧します。オペレーションはタグ別にまとめられており、クリックするとパラメーター、リクエストボディ、レスポンス、スキーマが表示されます。
- 大きな仕様書では、パス、summary、operationId でフィルターしてエンドポイントを探せます。
- オペレーションの cURL 例をコピーし、<TOKEN> や <API_KEY> のプレースホルダーを自分の認証情報に置き換えます。
よくある質問
Swagger や OpenAPI のファイルを表示するには?
YAML または JSON をボックスに貼り付けるか、ファイルを開きます。ビューアがバージョン(swagger: "2.0" または openapi: 3.0.x / 3.1.x)を判別し、エンドポイントをタグ別に一覧表示します。それぞれを展開すると、パラメーター、リクエストボディ、レスポンス、解決済みのスキーマを確認できます。ページを読み込んだ後はオフラインでも動作します。
OpenAPI バリデーターは何をチェックしますか?
仕様の構造ルールです:対応するバージョンのフィールド、title と version を持つ info、/ で始まる paths、description と有効なステータスコードを持つ空でない responses を備えたオペレーション、宣言済みかつ必須のパステンプレートのパラメーター、name・有効な in・schema を持つパラメーター、重複のないパラメーターと operationId、content を持つリクエストボディ、解決できる $ref、定義済みのスキームを指すセキュリティ要件。全リストはページの「チェック項目」にあります。すべてのスキーマキーワードを公式の JSON Schema に照らして検証するわけではありません。
宣言していないパスパラメーターがエラーになるのはなぜですか?
仕様では、パステンプレート内のすべての {name} に対し、パスまたはオペレーションのレベルで in: path と required: true を持つ対応するパラメーターが必要です。ドキュメントを JSON Schema に照らしてチェックするだけのバリデーターの中には、欠けていても受け入れるものがありますが、その場合コードジェネレーターはその引数のない関数を生成し、ドキュメントツールは正しく呼び出せないエンドポイントを表示してしまいます。
OpenAPI 3.1 や Swagger 2.0 も読み込めますか?
はい。Swagger 2.0 の body と formData のパラメーターはリクエストボディとして、produces と consumes はメディアタイプとして表示するので、3 つのバージョンすべてを同じように読めます。OpenAPI 3.1 の違いも反映しています。components や webhooks がある場合 paths は省略可能、responses も省略可能(ここでは警告)で、type: [string, "null"] は nullable として表示します。
外部の $ref ファイルも読み込みますか?
いいえ。他のファイルや URL への $ref(例:./schemas/user.yaml)は警告として一覧表示し、未解決として示します。ページは開いていないファイルを読めず、URL を勝手に取得することもないためです。複数ファイルに分かれた仕様書は、redocly bundle や swagger-cli bundle などで先に 1 つのドキュメントにまとめてください。
API 仕様書はアップロードされますか?
いいえ。解析、検証、表示はすべてブラウザ内で行われます。仕様書がどこかへ送信されることはありません。
OpenAPI 3.x と Swagger 2.0 の違い
• バージョンフィールド:swagger: "2.0" から openapi: 3.0.x、さらに 3.1.x へ。
• サーバー:2.0 は host、basePath、schemes、3.x は変数付きの servers リスト。
• リクエストボディ:2.0 は in: body(または formData)のパラメーター、3.x はメディアタイプごとの content を持つ requestBody。
• 再利用できる部品:2.0 はトップレベルの definitions、parameters、responses、3.x はそれらを securitySchemes、requestBodies、examples とともに components の下に置きます。
• 3.1 ではスキーマが JSON Schema 2020-12 に揃えられました:type にリストを指定可能(nullable: true の代わりに ["string", "null"])、examples は配列、webhooks が追加。
API ツールを壊しやすいエラー
• 宣言されていない、または required: true なしで宣言されたパスパラメーター。
• タイプミスのある $ref(schemas ではなく #/components/schema/User)。ドキュメントの一部が空になります。
• 重複した operationId。コードジェネレーターが失敗したり、メソッドが上書きされたりします。
• description のないレスポンス(ただの "OK" でも必須です)。
• 定義されていないスキームを指すセキュリティ要件。生成されたクライアントが認証できなくなります。
