説明
スキーマのexternalDocs.urlは、データモデルの意味や制約を説明する別の文書へのリンクです。リンクが誤っていると、補足情報を確認しにくくなります。OpenAPI 3.0の相対URLは、サーバーURLを基準に解決できます。
想定される影響
API利用者が項目の業務上の意味や細かな制約を見落とし、データ処理や連携で誤りが生じる場合があります。
対処方法
そのスキーマの実際の説明文書へリンクし、アドレスと内容を確認してください。相対リンクは意図した基準サーバーURLから解決し、独立した文書サイトには明示的なURLを使うことができます。
例
OpenAPI 3.0のUserスキーマで、相対パス/と明示的な文書アドレスを比較します。相対パスというだけで、不正なリンクになるわけではありません。
変更前
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"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"User": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"User": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"externalDocs": {
"url": "http://docs.my-api.com/store-orders.htm"
}
}
}
}
}
変更後のアドレスが、実際にUserモデルを説明しているか確認してください。externalDocsを変更しても、スキーマの検証制約自体は変わりません。