Description
A path parameter supplies part of a URL path and is always required. Omitting required: true or setting it to false on an in: path parameter does not meet the requirements of OpenAPI 3.0 or 2.0.
Potential impact
- Documentation may present the path value as optional and lead users to construct incorrect requests.
- Generators or validators may reject the definition or produce requests that differ from the server contract.
Remediation
Set required: true on every in: path parameter. Match its name to the path placeholder and verify the format required by the actual server.
Examples
These OpenAPI 3.0 excerpts show a path parameter. The complete document’s info and operation responses are omitted.
Before
json
{
"openapi": "3.0.0",
"paths": {
"/users/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": false,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
After
json
{
"openapi": "3.0.0",
"paths": {
"/users/{id}": {
"get": {
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
]
}
}
}
}
The first excerpt treats id as optional. The second sets required: true to state that the value in /users/{id} is required.