OpenAPI 3.1 バリデーター
OpenAPI 3.1 のドキュメントを JSON または YAML で貼り付けると、トップレベルの構造を確認できます。ツールは openapi フィールド、title と version を持つ info オブジェクト、paths オブジェクトを見ます。これは構造チェックなので、3.1 のスキーマキーワードは検証しません。3.1 に適したパターンの一部は、警告またはエラーとして報告される場合があるため、事前に把握しておいてください。
3.1 ドキュメントのチェック方法
-
1
3.1 の仕様を貼り付ける
`openapi: 3.1.0`（または他の 3.1.x の値）を含むドキュメントを、JSON または YAML のまま入力欄に貼り付けます。
-
2
チェックを実行する
結果のステップに進むと、エラーと警告が表示されます。
-
3
3.1 の注記を読む
指摘された項目が本当の誤りか、下で説明している 3.1 のパターンかを確認します。
-
4
完全な Linter で仕上げる
構造が正しくなったら、JSON Schema 2020-12 のルールを確認する完全なバリデーターを使います。
3.1 ファイルに対するこのツールの動作
バージョン 3.1 では、スキーマが JSON Schema 2020-12 に合わせられています。このバリデーターはスキーマの内部をまったく読みません。見るのはトップレベルと paths のエントリだけです。そのため、型の配列や const といった 3.1 のスキーマ機能は、合格にも不合格にもなりません。openapi フィールドの値自体も検証しません。どのような openapi フィールドも、存在していれば有効と扱われます。
注意すべき 3.1 のパターン 2 つ
| 3.1 ファイルのパターン | ツールの報告内容 |
|---|---|
webhooks オブジェクトがあり、paths オブジェクトがない |
エラー: Missing ‘paths’ object. |
パスの下に trace オペレーションがある |
警告: Unknown method ‘trace’ on the path |
パスアイテムのキーに $ref がある |
警告: Unknown method ‘$ref’ on the path |
OpenAPI 3.1 では、webhooks だけを記述して paths を省略できます。このツールは paths を必須としているため、仕様上は許容されるファイルでもエラーとして報告されます。空の paths: {} を追加すると、チェックを通過します。
ここで使われるメソッドの一覧は、get、post、put、patch、delete、head、options に加え、parameters、summary、description、servers です。trace メソッドは仕様に存在しますが、この一覧には含まれていないため、意図的に使っている場合は無視できる警告が出ます。警告があってもドキュメントが無効になることはありません。
実例
openapi: 3.1.0
info:
title: Events API
version: 2.0.0
webhooks:
newEvent:
post:
summary: Event delivered
結果: エラーが 1 件、“Missing ‘paths’ object.” です。paths: {} を追加すると、構造チェックに合格します。
このツールを使う場面と、さらに進むべき場面
このページは、3.1 のファイルを pull request に出す前や、パートナーと共有する前に、形式が正しいかを確認するために使ってください。チェックは高速で、メッセージも分かりやすいものです。構造が整った後も、3.1 のスキーマルールには完全な Linter が必要です。実際の誤りの多くはそこに潜んでいるためです。たとえば、不正な型宣言、壊れた参照、欠けているレスポンス定義などです。2 つの手順は代替ではなく、互いに補完するものとして扱ってください。
trace のように意図的な警告であれば、レビュアーが疑問に思わないよう pull request に書いておきましょう。警告は有効という判定を変えないので、残しても安全です。共有前に解決すべきなのはエラーの項目です。
よくある質問
いいえ。スキーマオブジェクトの内部は見ないため、JSON Schema 2020-12 のキーワードは検査されません。対象はトップレベルの構造と paths のエントリだけです。
チェックでは paths オブジェクトが必要です。webhooks だけの 3.1 ファイルには paths がないため、paths 不足のエラーが報告されます。空の paths: {} を追加すれば合格します。
いいえ。ツールが確認するのは openapi または swagger フィールドが存在することだけで、その値は確認しません。
必ずしもそうではありません。trace は仕様上有効なオペレーションです。ツールが既知のメソッド一覧に含めていないだけです。
関連ツール
Webpack設定ジェネレーター
素の JavaScript、React、Vue 向けに webpack 5 の webpack.config.js を生成します。TypeScript、Babel、CSS や Sass、画像、HtmlWebpackPlugin、開発サーバー、npm install のコマンドまでそろいます。
カラーティントジェネレーター
ベースカラーの明るい色合いを生成します。デザイン システム トークン、背景、ホバー状態を 3 ～ 20 段階でスケールします。
CMYK から RGB への変換
標準的な計算式で CMYK の割合をおおよその RGB 値と Hex 値に変換し、画面用にすばやく確認できます。
.gitignore ジェネレーター
Laravel、Node.js、Python、Rails のプロジェクト用除外ルールを組み合わせます。結果をコピーするか、.gitignore 入りの ZIP をダウンロードできます。個人用ルールは別に表示します。
16進数から10進数への変換ツール
16進数を10進数（10進法）に変換します。メモリアドレス、エラーコード、RGBチャンネル、任意精度の整数に対応します。
JSONからPythonデータクラスへの変換
JSONから、型ヒント、オプションフィールド、ネストされたクラス、およびdataclasses-jsonまたはPydanticサポートを備えたPythonデータクラスを生成します。
このツールは他の言語でも利用できます
- ตัวตรวจสอบ OpenAPI 3.1 [TH]
- Walidator OpenAPI 3.1 [PL]
- Công cụ kiểm tra OpenAPI 3.1 [VI]
- Validator OpenAPI 3.1 [ID]
- مدقق OpenAPI 3.1 [AR]
- OpenAPI 3.1 Validator [DE]
- Validador OpenAPI 3.1 [PT]
- Validador de OpenAPI 3.1 [ES]
- OpenAPI 3.1 검증기 [KO]
- OpenAPI 3.1-validerare [SV]
- Validateur OpenAPI 3.1 [FR]
- OpenAPI 3.1 Validator [NL]
- OpenAPI 3.1 Validator [EN]
- Validatore OpenAPI 3.1 [IT]
- Валидатор OpenAPI 3.1 [RU]
- OpenAPI 3.1 Doğrulayıcı [TR]
- OpenAPI 3.1 验证器 [ZH]