Description
The root externalDocs.url links to additional documentation for the API as a whole. Address errors or unintended destinations hinder understanding. OpenAPI 3.0 also permits relative references resolved against the server URL.
Potential impact
Consumers may be unable to find operational guidance or detailed explanations, delaying API use and troubleshooting.
Remediation
Specify the actual API-wide documentation address and check the link. Resolve relative URLs against the intended server address; use an absolute URL when the documentation is on an independent site.
Examples
These OpenAPI 3.0 examples compare / with a documentation URL on another site. Since / can be a valid relative reference, the question is whether its actual destination serves the intended purpose.
Before
{
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"externalDocs": {
"url": "/"
}
}
After
{
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"externalDocs": {
"url": "http://docs.my-api.com/store-orders.htm"
}
}
The revised document identifies a particular page. Replace the example address with documentation for the actual API and check its content and accessibility.