Description
An OpenAPI 3.0 Parameter Object must use either schema or content, but not both. Defining both describes the same parameter in two ways and violates their mutual-exclusion requirement.
Potential impact
- Documentation renderers and code generators may reject the definition or handle it inconsistently.
- API consumers may be unsure which parameter representation to send.
Remediation
Use schema for a value’s structure and serialization, or content for a media-type-based representation, and remove the other property. Give content exactly one media type. Validate the revised document and confirm that it matches actual requests.
Examples
These excerpts compare parameter definitions. The response definition for /users/{id} is omitted.
Before
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/{id}": {
"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"
}
]
}
]
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the API the version",
"required": true,
"schema": {
"type": "integer"
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
}
}
}
}
}
]
},
"/users/{id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The user ID",
"schema": {
"type": "integer",
"minimum": 1
},
"content": {
"application/json": {
"schema": {
"type": "integer"
}
}
}
}
]
}
}
}
}
After
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/{id}": {
"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"
}
]
}
]
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of the API the version",
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/users/{id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The user ID",
"schema": {
"type": "integer",
"minimum": 1
}
}
]
}
}
}
}
The revised example keeps only schema to describe the integer format and constraints of each path parameter.