コンテンツへスキップ

OpenAPI・Swagger ビューア&バリデーター — YAML / JSON 対応

OpenAPI 3.x や Swagger 2.0 の仕様書を貼り付けると、タグ別のドキュメントとして閲覧でき、構造上のエラーをチェックし、エンドポイントごとの cURL 例も得られます。

OpenAPI 3.0 · Bookstore API 1.2.0 · 4 件のオペレーション · エラー 1 件、警告 0 件

検証

  • エラー パスで {itemId} を使っていますが、「itemId」という名前の in: path パラメーターが宣言されていません。
    場所:paths./orders/{orderId}/items/{itemId}.get
チェック項目

ビューアーは、OpenAPI 3.0 / 3.1 と Swagger 2.0 の仕様にある以下の構造ルールをチェックします。ドキュメントの完全な JSON Schema 検証ではなく、個々のスキーマキーワード(minimum、pattern、format など)はチェックしません。

  • ドキュメントが有効な YAML または JSON である。
  • openapi: 3.0.x または 3.1.x、あるいは swagger: "2.0" が宣言されている。
  • info があり、title と version(文字列)を持つ。
  • paths がある(3.1 では components や webhooks があれば省略可能)。
  • すべてのパスが / で始まる。
  • パスアイテムには HTTP メソッド、parameters、$ref、summary、description、servers(または x- 拡張)だけが含まれる。
  • すべてのオペレーションに responses がある(2.0 と 3.0 ではエラー、3.1 では警告)。
  • responses が空でない。
  • レスポンスのキーはステータスコード(200)、default、または(3.x では)2XX などの範囲である。
  • すべてのレスポンスに description がある。
  • operationId の値が一意である。
  • パス内のすべての {name} に、対応する in: path のパラメーターがある。
  • すべての in: path のパラメーターがパスに現れる。
  • パスパラメーターが required: true を持つ。
  • すべてのパラメーターが name と in を持つ。
  • in が query、header、path、cookie のいずれかである(2.0 では query、header、path、formData、body)。
  • 同じ name と in のパラメーターが 2 回記載されていない。
  • パラメーターが schema または content を持つ(2.0 では body パラメーターは schema、その他は type)。
  • 2.0:body パラメーターは最大 1 つで、formData と併用しない。
  • 3.x:requestBody が content を持つ。
  • すべてのローカル $ref(#/…)が存在するものを指している。
  • 他のファイルや URL への参照を報告する(取得はしない)。
  • セキュリティ要件が定義済みのセキュリティスキームを指している。

ドキュメント: Bookstore API 1.2.0

A small example API. Edit it or paste your own spec.

ベース URL:https://api.example-bookstore.com/v1

Books

Browse and manage the catalogue

GET/booksList books
POST/booksAdd a book
GET/books/{bookId}Get one book

Orders

Place and track orders

GET/orders/{orderId}/items/{itemId}Get an order line

スキーマ

NewBook
Book
Author
OrderItem

すべてブラウザ内で動作します。API 仕様書がアップロードされることはなく、外部の $ref も取得しません。 すべての無料ツールを見る.

不具合や改善できそうな点を見つけましたか?いただいたメッセージはすべて読み、すぐに対応します。

この OpenAPI ビューア兼バリデーターは、YAML または JSON の OpenAPI 3.0・3.1、Swagger 2.0 ドキュメントを読み込み、閲覧しやすい API ドキュメントとして表示します。すべてのエンドポイントをタグ別にまとめ、パラメーター、リクエストボディ、レスポンス、スキーマに加えて、すぐに実行できる cURL コマンドも示します。仕様書を貼り付けるかファイルを開くだけで、アップロードは一切ないため、社内向けや未公開の API も外部に漏れません。

バリデーターは仕様から取り出した 23 の構造チェックを実行し、その一覧はページに記載しています。info と paths があること、レスポンスに description と有効なステータスコードがあること、パス内のすべての {parameter} が必須のパスパラメーターとして宣言されていること、operationId が一意であること、$ref が解決できること、セキュリティ要件が定義済みのスキームを指していることなどです。これらはコードジェネレーターやドキュメントツールを壊すエラーです。仕様の公式 JSON Schema に対する完全な検証ではないため、ここで合格した仕様書にも、たとえばスキーマのキーワードのつづり間違いが残っている可能性があります。他のファイルへの外部 $ref は一覧表示しますが、取得はしません。

使い方

  1. openapi.yaml、openapi.json、swagger.json を貼り付けるか、ファイルを開きます。最初はサンプルの API が読み込まれています。
  2. ステータス行と「検証」の一覧を確認します。各問題にはルールと場所(例:paths./pets/{id}.get)が示されます。
  3. ドキュメントを閲覧します。オペレーションはタグ別にまとめられており、クリックするとパラメーター、リクエストボディ、レスポンス、スキーマが表示されます。
  4. 大きな仕様書では、パス、summary、operationId でフィルターしてエンドポイントを探せます。
  5. オペレーションの 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" でも必須です)。

• 定義されていないスキームを指すセキュリティ要件。生成されたクライアントが認証できなくなります。