Description
Variables used in an OpenAPI 3.0 server URL must be defined in that server object’s variables map. Each needs a string default to use when no alternative value is supplied.
Potential impact
Without defined substitution values, documentation tools or clients may be unable to construct the intended server address.
Remediation
Define a variable with the same name as each URL placeholder and provide a valid string default. Consider enum for restricted choices, and verify the completed URLs for default and selected values.
Examples
These Link excerpts focus on server URL variables. An operationId or operationRef identifying the target operation is also required but omitted here.
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": "https://development.{server}.com/{base}"
}
}
}
}
},
"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.{server}.com/{base}",
"variables": {
"base": {
"default": "v2"
},
"server": {
"default": "gigant-server"
}
}
}
}
}
}
},
"operationId": "listVersionsv2"
}
}
}
}
The first example provides no values for server and base. With the added defaults, the URL resolves to https://development.gigant-server.com/v2.