Description
Accept is the HTTP header a client uses to indicate preferred response formats. OpenAPI 3.0 specifies that an ordinary header parameter with this name is ignored, so describe the contract through response media types.
Potential impact
The declared parameter may not appear in documentation tools, or consumers may confuse business input with response-format negotiation.
Remediation
Describe response formats using response content in OpenAPI 3.0 or produces in Swagger 2.0. Model a genuinely separate input as an appropriate parameter and verify the server and client contract. This does not mean that the HTTP Accept header itself must not be used.
Examples
These OpenAPI 3.0 excerpts compare the name and location of ID inputs. The separate path parameter definition for /users/{id} is omitted.
Before
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"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"
}
]
}
]
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Accept",
"in": "header",
"description": "ID of the API the version",
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/users/{id}": {
"get": {
"parameters": [
{
"in": "header",
"name": "Accept",
"required": true,
"description": "The user ID",
"schema": {
"type": "integer",
"minimum": 1
}
}
],
"responses": {
"200": {
"description": "200 response"
}
}
}
}
}
}
After
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"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"
}
]
}
]
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "query",
"description": "ID of the API the version",
"required": true,
"schema": {
"type": "integer"
}
}
]
},
"/users/{id}": {
"get": {
"responses": {
"200": {
"description": "200 response"
}
},
"parameters": [
{
"in": "header",
"name": "id",
"required": true,
"description": "The user ID",
"schema": {
"type": "integer",
"minimum": 1
}
}
]
}
}
}
}
The revised ID inputs use query or a separate header parameter. They do not replace response-format negotiation, and the actual API must support those input locations.