説明
OpenAPI 3.0 の components.links は、応答と後続の操作との関係を再利用可能なリンクとして定義します。存在しないリンクを $ref で参照すると、文書ツールがその関係を解釈できない場合があります。
想定される影響
- 応答後に呼び出せる操作の案内が文書から欠落する可能性があります。
- 参照エラーにより仕様書の検証やコード生成が失敗する場合があります。
対処方法
リンクの $ref を、実在する components.links の定義に合わせてください。応答の links では名前付きの項目内に参照を置き、リンク先の操作も存在することを確認してください。外部参照の場合は対象の文書も検証してください。
例
最初の例の links.repository は、定義されていない APIWrongRepository を参照しています。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MyObject"
}
}
}
},
"links": {
"repository": {
"$ref": "#/components/links/APIWrongRepository"
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"links": {
"APIRepository": {
"operationId": "listVersionsv2"
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MyObject"
}
}
}
},
"links": {
"repository": {
"$ref": "#/components/links/APIRepository"
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"links": {
"APIRepository": {
"operationId": "listVersionsv2"
}
}
}
}
変更後は APIRepository を参照します。この例のリンクは同じ listVersionsv2 操作を指しており、リンクの宣言だけでクライアントが操作を自動実行するわけではありません。