説明
OpenAPI 3.0では相対サーバーURLを使用でき、OpenAPI文書を提供する場所を基準に解決されます。相対URL自体は不正ではありませんが、文書の配信場所が変わると意図しないサーバーを指す場合があります。
想定される影響
ドキュメントツールやクライアントが、誤ったエンドポイントへリクエストを送るおそれがあります。ホスト名に見えるパスを、実際のホストアドレスと取り違えないよう注意が必要です。
対処方法
文書の配信場所を基準に相対URLを解決し、意図したアドレスになることを確認してください。その場所に依存しないサーバーを指定する場合は、HTTPSスキームとホストを含む絶対URLを使ってください。
例
LinkのサーバーURLを比較する抜粋です。対象操作のoperationIdまたはoperationRefは省略しています。どちらのURL形式も許可されていますが、同じ接続先を表すわけではありません。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"summary": "List API versions",
"responses": {
"200": {
"description": "the user being returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"links": {
"address": {
"server": {
"url": "/development.gigantic-server.com/v1"
}
}
}
}
},
"operationId": "listVersionsv2"
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"summary": "List API versions",
"responses": {
"200": {
"description": "the user being returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"links": {
"address": {
"server": {
"url": "https://development.gigantic-server.com/v1"
}
}
}
}
},
"operationId": "listVersionsv2"
}
}
}
}
最初の/development.gigantic-server.com/v1は、文書を提供するホスト上のパスです。後の絶対URLはdevelopment.gigantic-server.comというホストを明示します。意図した配置に合う形式を選んでください。