説明
操作のないパス項目からは、そのパスが対応するリクエストを確認できません。ただし、OpenAPI 3.0 と 2.0 はアクセス制御のために空のパス項目を認めており、$ref の参照先で操作が定義されている場合もあります。
想定される影響
公開すべき操作が抜けると、利用者が対応するメソッドを把握できず、文書を使った連携やテストが不完全になる場合があります。文書で操作を隠すだけでは、サーバーへのアクセスは遮断されません。
対処方法
文書の対象者に公開する操作と、参照先のパス項目を確認してください。実際に提供し、文書に公開すべき HTTP メソッドとレスポンスだけを追加し、意図的に空にした項目は維持してください。サーバーの認証と権限制御は別途適用してください。
例
OpenAPI 3.0 の空のパス項目と操作を含む項目の比較です。info は省略しています。空の項目自体は仕様違反ではありません。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/": {}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
変更後は GET / と 200 レスポンスを説明しています。実際にこの操作を提供し、対象者への文書化が必要な場合に適切な追加です。