説明
components.callbacks に定義したコールバックは、操作から参照しないと、その操作のコールバック契約に結び付きません。使用するコールバックは操作の callbacks から参照し、他の文書でも使わない不要な定義は整理してください。
想定される影響
- 未使用のコールバックが、実装済みの API 機能と誤解される可能性があります。
- API の変更時に不要な定義まで確認する必要があり、文書の保守負担が増えます。
対処方法
コールバックが必要な操作の callbacks から、コンポーネントを $ref で参照してください。削除前に他の文書やツールからの参照も確認し、変更後に参照先とコールバック URL の式が正しいか検証してください。
例
以下はコールバックの定義と操作への接続を比較する例です。inProgressUrl を指定する POST のリクエスト本文は省略しています。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success"
}
}
}
}
},
"components": {
"callbacks": {
"inProgress": {
"{$request.body#/inProgressUrl}": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"post": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "Success"
}
},
"callbacks": {
"myEvent": {
"$ref": "#/components/callbacks/inProgress"
}
}
}
}
},
"components": {
"callbacks": {
"inProgress": {
"{$request.body#/inProgressUrl}": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
}
}
}
}
}
}
}
変更後は callbacks.myEvent から inProgress を参照します。この宣言はコールバック契約を文書化するもので、サーバーからの実際の要求を実装するものではありません。