Multiple content entries in an OpenAPI 3.0 parameter

Description

In an OpenAPI 3.0 Parameter Object, content must contain exactly one media type entry. Providing multiple entries, such as application/json and application/xml together, violates the Parameter Object structure.

Potential impact

Validation may reject the specification, or client generation may fail.
API users may be unsure which format to use for the parameter value.

Remediation

Keep the one media type actually used in the parameter’s content, and check its schema and examples. Do not specify both schema and content on the same Parameter Object. If multiple request body formats are needed, design that request body contract separately.

Examples

These examples compare two media types with one at operation and path parameter levels. The referenced User schema and external example files must be supplied separately.

Before

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "paths": {
    "/user/{id}": {
      "parameters": [
        {
          "description": "ID of the API version",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/User"
              },
              "examples": {
                "user": {
                  "summary": "User Example",
                  "externalValue": "http://foo.bar/examples/user-example.json"
                }
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/User"
              },
              "examples": {
                "user": {
                  "summary": "User Example in XML",
                  "externalValue": "http://foo.bar/examples/user-example.xml"
                }
              }
            }
          },
          "name": "id",
          "in": "path"
        }
      ]
    },
    "/{id}": {
      "get": {
        "summary": "List API versions",
        "parameters": [
          {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "examples": {
                  "user": {
                    "summary": "User Example",
                    "externalValue": "http://foo.bar/examples/user-example.json"
                  }
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                },
                "examples": {
                  "user": {
                    "summary": "User Example in XML",
                    "externalValue": "http://foo.bar/examples/user-example.xml"
                  }
                }
              }
            },
            "name": "id",
            "in": "path",
            "description": "ID of the API version",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "foo": {
                    "value": {
                      "versions": [
                        {
                          "updated": "2011-01-21T11:33:21Z",
                          "id": "v2.0",
                          "links": [
                            {
                              "rel": "self",
                              "href": "http://127.0.0.1:8774/v2/"
                            }
                          ],
                          "status": "CURRENT"
                        }
                      ]
                    }
                  }
                }
              }
            },
            "description": "200 response"
          }
        },
        "operationId": "listVersionsv2"
      }
    }
  }
}

After