Description
OpenAPI 3.0 components.links defines reusable relationships between responses and subsequent operations. A $ref to a missing link can prevent documentation tools from resolving that relationship.
Potential impact
- Documentation may omit guidance about an operation available after the response.
- Reference errors can cause specification validation or code generation to fail.
Remediation
Match the link $ref to an existing components.links definition. Put the reference inside a named entry in the response’s links, and check that the linked operation also exists. Validate the target document when using an external reference.
Examples
In the first example, links.repository references APIWrongRepository, which is not defined.
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"
}
}
}
},
"links": {
"repository": {
"$ref": "#/components/links/APIWrongRepository"
}
}
}
}
}
}
},
"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 example references APIRepository. This illustrative link targets the same listVersionsv2 operation; declaring the link does not make a client invoke it automatically.