OpenAPIの点検
OpenAPI Linter
OpenAPI文書の抜けたレスポンス・使われていないスキーマ・どこも指していない参照など、コード生成器を壊す不備を点検します。
OpenAPIの3.0や3.1の文書を点検し、コード生成器を壊すもの、クライアントのライブラリに嘘をつかせるもの、あるいは仕様がそもそも要求しているものを見つけます。規則は手で書いてあり、ページに一覧してあります。作法の好みではなく、問題です。
OpenAPI 文書
openapi.yaml を置く
このタブの中だけで読みます。
指摘24件
エラーschema-array-itemscomponents.schemas.Order.items
`type: array` なのに `items` がありません。
エラーpath-param-undeclaredGET /orders/{orderId}
経路の `{orderId}` はパラメータとして宣言されていません。
エラーresponse-descriptionGET /orders/{orderId}
`200` のレスポンスに description がありません。
エラーschema-array-itemsGET /orders/{orderId} responses["200"].content["application/json"].items
`type: array` なのに `items` がありません。
エラーinfo-missinginfo
`info.version` がありません。これは API のバージョンで、OpenAPI のバージョンではありません。
エラーoperation-id-duplicatePOST /orders/{orderId}
operationId `getOrder` は GET /orders/{orderId} にもあります。
エラーpath-param-requiredPOST /orders/{orderId}
`in: path` パラメータ `id` に `required: true` がありません。
エラーpath-param-undeclaredPOST /orders/{orderId}
経路の `{orderId}` はパラメータとして宣言されていません。
エラーpath-param-unusedPOST /orders/{orderId}
`in: path` パラメータ `id` は経路に現れません。
警告path-trailing-slash/orders/
この経路は `/` で終わっています。
警告schema-unusedcomponents.schemas.Customer
このスキーマを参照しているものがありません。
警告operation-id-missingGET /orders/
operationId がありません。
警告response-errorGET /orders/
4xx のレスポンスがありません。
警告description-missingGET /orders/{orderId}
summary も description もありません。
警告response-errorGET /orders/{orderId}
4xx のレスポンスがありません。
警告description-missingPOST /orders/{orderId}
summary も description もありません。
警告response-errorPOST /orders/{orderId}
4xx のレスポンスがありません。
警告response-successPOST /orders/{orderId}
2xx や 3xx のレスポンスがありません。
参考tag-missingGET /orders/
タグがありません。
参考tag-missingGET /orders/{orderId}
タグがありません。
参考parameter-descriptionPOST /orders/{orderId}
パラメータ `id` に description がありません。
参考response-default-onlyPOST /orders/{orderId}
レスポンスが `default` だけです。
参考tag-missingPOST /orders/{orderId}
タグがありません。
参考servers-missingservers
サーバーが1つも並んでいないので、基準 URL は `/` です。
OpenAPI
3.0.3
操作
3
エラー
9
警告
9
参考
6
手で書いたルール集です。コード生成器がつまずくもの、クライアントライブラリが嘘をつくようになるもの、仕様が本当に求めているもの — 好みではなく問題を拾います。Spectral のルールセットは読み込みません。
2つのバージョンの差を見るなら OpenAPI 変更比較をどうぞ。
使い方
文書を貼り付けます
JSONでもYAMLでも、3.0でも3.1でも構いません。このタブの中でパースします。アップロードは一切しません。
まずエラーから片づけます
指摘ごとに、規則のidと、文書の中の正確な位置が付きます。エラーは実際に問題を起こすもので、警告はたいてい問題を起こすものです。
指摘に驚いたら、規則の一覧を読みます
規則はすべて、深刻度と、なぜ存在するのかとともに書き出してあります。だから、納得できない指摘も、少なくとも読める理由のある主張です。
よくある質問
自分のSpectralのルールセットを読み込めますか
読み込めません。これは固定の、手で書いた規則の集まりで、作法の好みではなく問題を基準に選んであります。Spectralの設定を持っているなら、それを尊重してくれるのはSpectralです。
Swagger 2.0のファイルを読んでくれません
そのとおりです。2.0は少し古い3.0ではなく、文書の形が別のもので、規則の半分は当てはまりません。先に変換してください。`swagger2openapi`が通常の経路です。
外部の`$ref`をたどってくれませんでした
文書の中の`$ref`は解決します。別のファイルを指すものは、あなたの機械にしかないパスから取ってくることになります。検査が完全ではなく、通ったわけでもないと分かるように、注記として報告します。
`operationId`が無いことが警告になるのはなぜですか
生成器が、その操作のために出す関数の名前にそれを使うからです。無ければパスとメソッドから作った名前になり、パスが変わった瞬間にその名前も変わります。APIの中の1つの改名が、すべてのクライアントの改名になるということです。
ここから渡せます
JSONからJSON Schema
JSON to JSON Schema
1つまたは複数の実例からJSON Schemaを推論し、見つかった形を合わせて1つにします。
JSON Schema検証
JSON Schema Validator
文書をJSON Schemaで検証し、通らなかった箇所をインスタンスのパスとともに挙げます。
curlをコードに変換
curl to Code
curlのコマンドをfetch・axios・Pythonのrequests・Go・PHP・PowerShellのコードに変換します。
OpenAPIの差分比較
OpenAPI Diff
2つのOpenAPI文書を比べ、互換性を壊す変更と足しただけの変更を分けて示します。
次の一手
このツールが出したものをそのまま受け取れる道具です。
curlをコードに変換
curl to Code
curlのコマンドをfetch・axios・Pythonのrequests・Go・PHP・PowerShellのコードに変換します。
JSON Schema検証
JSON Schema Validator
文書をJSON Schemaで検証し、通らなかった箇所をインスタンスのパスとともに挙げます。
OpenAPIの差分比較
OpenAPI Diff
2つのOpenAPI文書を比べ、互換性を壊す変更と足しただけの変更を分けて示します。
YAMLフォーマッター・検証
YAML Formatter & Validator
YAMLのインデントを揃えて検証し、パーサを壊すタブやアンカーの誤りに印を付けます。
JSON⇄CSV変換
JSON ⇄ CSV
入れ子のJSONをドット記法の列名で平らに開くか、表からオブジェクトを組み直します。
JSON差分比較
JSON Diff
キーの順序を無視して2つのJSONを構造で比べ、追加・削除・変更されたパスを挙げます。