Description
OpenAPI 3.0 permits relative server URLs, resolved against the location serving the OpenAPI document. A relative URL is not inherently invalid, but moving the document can make it identify an unintended server.
Potential impact
Documentation tools or clients may send requests to the wrong endpoint. A path that resembles a hostname is particularly easy to mistake for an actual host address.
Remediation
Verify the result of resolving the relative URL against the document’s serving location. To identify a server independently of that location, use an absolute URL containing the HTTPS scheme and host.
Examples
These excerpts compare a Link’s server URL; its target operationId or operationRef is omitted. Both URL forms are allowed, but they do not identify the same target.
Before
{
"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"
}
}
}
}
After
{
"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"
}
}
}
}
The first /development.gigantic-server.com/v1 is a path on the document’s host. The absolute URL explicitly identifies the development.gigantic-server.com host. Choose the form that fits the intended deployment.