説明
操作レベルのexternalDocs.urlは、そのAPI呼び出しの詳細文書へのリンクです。誤ったアドレスや無関係な資料は、個別の規則の理解を妨げます。OpenAPI 3.0では、相対URLもサーバー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",
"externalDocs": {
"url": "/"
},
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}
変更後
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",
"externalDocs": {
"url": "http://docs.my-api.com/store-orders.htm"
},
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}
変更後は文書ページを明示しています。実際にその操作を説明する資料か確認し、例のアドレスを置き換えてください。