説明
OpenAPI の paths は API のパスと操作を記述します。空の paths: {} にはパス情報がありませんが、OpenAPI 3.0 と 2.0 はアクセス制御のために空のオブジェクトを認めています。必須の paths フィールドの省略や null は、空のオブジェクトとは異なります。
想定される影響
対象者に必要なパスまで欠落すると、API の把握や文書に基づく連携・テストが難しくなります。文書が空でも、実際の API が無効化されたり、アクセスを遮断されたりするわけではありません。
対処方法
文書の対象者と公開範囲を確認し、必要な実際のパス、操作、レスポンスを paths に定義してください。意図的な空のオブジェクトは維持できます。サーバーの認証と権限制御は、文書の公開範囲とは別に管理してください。
例
OpenAPI 3.0 のパスの公開範囲を比較する抜粋です。info は省略しています。変更前の空のオブジェクトは、意図的な文書の絞り込みにも使えます。
変更前
json
{
"openapi": "3.0.0",
"paths": {}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
変更後は GET / とレスポンスを公開しています。実際に対応し、この文書の対象者に提供する操作である場合に追加してください。