説明
OpenAPI 3.0 のコールバックは、API 提供側が行う後続の要求を文書化します。#/components/callbacks/ で始まるローカルの $ref が存在しない名前を指すと、ツールはコールバックの定義を解決できません。
想定される影響
- 非同期イベントや Webhook の流れが文書から欠けたり、誤って表示されたりする可能性があります。
- 参照検証のエラーによって文書やコードの生成が失敗する可能性があります。
- API の利用者が後続の要求の URL や形式を誤解する可能性があります。
対処方法
ローカルのコールバック $ref を components.callbacks に存在する名前と完全に一致させてください。改名時はすべての参照も変更し、外部参照の場合は URI と参照先文書も検証してください。コールバック URL の式に必要な実際の要求値も確認してください。
例
以下の POST 操作は inProgress を参照しますが、最初の文書には onProgress しかありません。コールバック URL を渡すリクエスト本文の定義は省略しています。
変更前
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": {
"onProgress": {
"{$request.body#/onProgressUrl}": {
"delete": {
"responses": {
"204": {
"description": "Deleted"
}
}
}
}
}
}
}
}
変更後
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}": {
"delete": {
"responses": {
"204": {
"description": "Deleted"
}
}
}
}
}
}
}
}
変更後は参照先の inProgress を定義しています。このコールバック URL の式を使うには、実際のリクエスト本文に inProgressUrl の値が必要です。