説明
最上位のexternalDocs.urlは、API全体に関する追加文書へのリンクです。アドレスの誤りや意図しない接続先は、利用者の理解を妨げます。OpenAPI 3.0では、サーバーURLを基準に解決する相対参照も許可されています。
想定される影響
運用ガイドや詳細説明が見つからず、APIの利用や問題解決に時間がかかる場合があります。
対処方法
API全体に対応する実際の文書アドレスを指定し、リンクを確認してください。相対URLは意図したサーバーアドレスを基準に解決し、文書が独立したサイトにある場合は絶対URLを使用してください。
例
OpenAPI 3.0で/と外部サイトの文書URLを比較します。/は有効な相対参照になり得るため、実際のリンク先が目的に合うかが重要です。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0",
"contact": {
"name": "contact",
"url": "https://www.google.com/",
"email": "user@gmail.com"
}
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"externalDocs": {
"url": "/"
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0",
"contact": {
"name": "contact",
"url": "https://www.google.com/",
"email": "user@gmail.com"
}
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"externalDocs": {
"url": "http://docs.my-api.com/store-orders.htm"
}
}
変更後は特定の文書ページを明示します。例のアドレスを実際のAPI全体に関する文書へ置き換え、内容とアクセス可能性を確認してください。