本文へスキップ

OpenAPIの点検

OpenAPI Linter

OpenAPI文書の抜けたレスポンス・使われていないスキーマ・どこも指していない参照など、コード生成器を壊す不備を点検します。

OpenAPIの3.0や3.1の文書を点検し、コード生成器を壊すもの、クライアントのライブラリに嘘をつかせるもの、あるいは仕様がそもそも要求しているものを見つけます。規則は手で書いてあり、ページに一覧してあります。作法の好みではなく、問題です。

🔒 ブラウザの中だけで動きますopenapilintapiquality

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 のルールセットは読み込みません。

OpenAPI 3.0 と 3.1 の文書を JSON か YAML で受け取ります。Swagger 2.0 は先に 3 へ上げてください。文書の中の `$ref` は辿りますが、別のファイルを指すものは確認できないため参考として報告します。

2つのバージョンの差を見るなら OpenAPI 変更比較をどうぞ。

使い方

  1. 文書を貼り付けます

    JSONでもYAMLでも、3.0でも3.1でも構いません。このタブの中でパースします。アップロードは一切しません。

  2. まずエラーから片づけます

    指摘ごとに、規則のidと、文書の中の正確な位置が付きます。エラーは実際に問題を起こすもので、警告はたいてい問題を起こすものです。

  3. 指摘に驚いたら、規則の一覧を読みます

    規則はすべて、深刻度と、なぜ存在するのかとともに書き出してあります。だから、納得できない指摘も、少なくとも読める理由のある主張です。

よくある質問

自分のSpectralのルールセットを読み込めますか

読み込めません。これは固定の、手で書いた規則の集まりで、作法の好みではなく問題を基準に選んであります。Spectralの設定を持っているなら、それを尊重してくれるのはSpectralです。

Swagger 2.0のファイルを読んでくれません

そのとおりです。2.0は少し古い3.0ではなく、文書の形が別のもので、規則の半分は当てはまりません。先に変換してください。`swagger2openapi`が通常の経路です。

外部の`$ref`をたどってくれませんでした

文書の中の`$ref`は解決します。別のファイルを指すものは、あなたの機械にしかないパスから取ってくることになります。検査が完全ではなく、通ったわけでもないと分かるように、注記として報告します。

`operationId`が無いことが警告になるのはなぜですか

生成器が、その操作のために出す関数の名前にそれを使うからです。無ければパスとメソッドから作った名前になり、パスが変わった瞬間にその名前も変わります。APIの中の1つの改名が、すべてのクライアントの改名になるということです。

ここから渡せます

次の一手

このツールが出したものをそのまま受け取れる道具です。