OpenAPI の必須パラメータの一覧
OpenAPI のどの API にどのパラメータが必須か、一覧で見つける。
OpenAPI 3.x の定義(JSON)を貼り付けると、エンドポイント(パスとメソッド)ごとの必須パラメータを、場所(path・query・header・cookie)・必須の理由・定義元つきで一覧にします。Path Item の共通パラメータと Operation の上書き、$ref の参照も反映します。入力はブラウザの中だけで処理します。
OpenAPI の定義を貼り付けて必須パラメータを一覧にする
入力した内容は送信されません。貼り付けた文字や選んだファイルは、お使いのブラウザの中だけで処理します。本サイトのサーバーや第三者へ送信・保存しません(通信を禁止する設定でページを配信しています)。
結果
エラー 0 件・警告 0 件・情報 1 件
指摘(エラー・警告・情報)
- 情報 出力全体 requestBody(本文)の required と、セキュリティ(認証)の要件は含めていません。パラメータ(query・header・path・クッキー)だけの一覧です。
| オペレーションの数 | 1 個 |
|---|---|
| 必須パラメータの数 | 2 件 |
必須パラメータの一覧
| パス | メソッド | パラメータ名 | 場所(in) | 必須の理由 | 定義元 |
|---|---|---|---|---|---|
| /users/{id} | GET | id | path | path は常に必須(required: true) | Operation |
| /users/{id} | GET | X-Trace | header | required: true | Operation |
初期表示は入力例「path と header の必須パラメータ」の結果です。入力を変えるとその場で処理し直します。判定の根拠は仕様と根拠にまとめています。
ご利用にあたって
- 一覧は貼り付けた定義の内容にもとづきます。実際の API サーバーの挙動とは異なることがあります。
- 大きな定義はお使いの端末の性能によって処理に時間がかかることがあります。
使い方
- OpenAPI 3.x の定義全体(JSON 形式)をテキスト欄に貼り付けるか、JSON ファイルを選びます。YAML のときは先に JSON に変換します。
- 表で、パス・メソッドごとの必須パラメータと、その場所(in)・必須の理由・定義元を確かめます。
- 警告が出たら、path のパラメータの required や、パスの {…} との名前の一致、参照先の有無を直して貼り直します。
- 共通のパラメータを Path Item に書いているときは、定義元の列で Operation が上書きしたものを見分けます。
入力例と結果
代表的な入力・境界の入力・壊れた入力の例です。例ごとに入力・出力・指摘と、その結果になる理由(検算)を載せています。
| 入力例 | 結果 |
|---|---|
| path と header の必須パラメータ | エラー 0 件・警告 0 件・情報 1 件 |
| Path Item の共通パラメータを Operation が上書き | エラー 0 件・警告 0 件・情報 1 件 |
| components の定義を $ref で参照 | エラー 0 件・警告 0 件・情報 1 件 |
| path なのに required: true がない | エラー 0 件・警告 1 件・情報 1 件 |
| OpenAPI 2.0(Swagger)の定義は読まない | エラー 1 件・警告 0 件・情報 0 件 |
このツールでできないこと(制約)
- YAML 形式、外部ファイルや URL への参照は読めません。同じファイル内の #/… の参照だけ解決します。
- リクエスト本文(requestBody)の必須や、認証(security)の要件は含めません。パラメータの一覧です。
- OpenAPI 2.0(Swagger)の定義は対象外です。仕様の確認は 3.1.0 で行ったもので、3.0 系の細部の違いまでは確かめていません。
- OpenAPI 全体の文法や、パラメータの schema(型・形式)の正しさは検査しません。
よくある質問
required を書かない query パラメータは必須ですか?
いいえ。OpenAPI 3.1.0 の Parameter Object では required は省略すると false として扱われます。必須にするには required: true と書きます。ただし path のパラメータだけは required: true が必須です。
Path Item の共通パラメータを Operation で消すことはできますか?
できません。Path Item の parameters は Operation で上書きできますが、削除はできないと仕様にあります。必須でなくしたいときは、同じ name と in で required: false と書いて上書きします。
貼り付けた定義はどこかに送られますか?
送られません。一覧づくりはお使いのブラウザの中だけで行い、ページは通信を禁止する設定(CSP の connect-src)で配信しています。社外秘の API の定義でも内容を送信しませんが、共用の端末では使い終わったらページを閉じてください。