Description
A link defined in components.links does not describe a relationship from a response to another operation unless that response references it. Connect needed links through the response’s links and remove unnecessary definitions.
Potential impact
- Documentation may omit the relationship to an operation available after a response.
- Unused link definitions can make it harder to compare the documented and actual API flow.
Remediation
Create a named entry in the response’s links and reference the link component with $ref. Check that both the link and its target operation exist. Remove unneeded definitions after checking whether other documents or tools use them.
Examples
The first example defines APIRepository without referencing it from the response.
Before
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MyObject"
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"links": {
"APIRepository": {
"operationId": "listVersionsv2"
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MyObject"
}
}
}
},
"links": {
"repository": {
"$ref": "#/components/links/APIRepository"
}
}
}
}
}
}
},
"components": {
"schemas": {
"MyObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"links": {
"APIRepository": {
"operationId": "listVersionsv2"
}
}
}
}
The second response references APIRepository through links.repository. The illustrative link targets the same listVersionsv2 operation; it does not cause clients to call that operation automatically.