In OpenAPI, when do you use requestBody instead of a parameter, and what does its content map key on?

## The 3.x split Swagger 2.0 had a single `parameters` list containing everything, including `in: body` and `in: formData`. OpenAPI 3.x separated the two ideas: a **Parameter Object** describes a value that travels in the URL, a header or a cookie; the **Request Body Object** describes the message body. An operation has at most one `requestBody` and any number of parameters. If a candidate mentions `in: body`, they are describing 2.0. ## The Request Body Object Three fields: - **`description`** — free text, CommonMark allowed. - **`required`** — boolean, **defaults to `false`**. This is the single most commonly missed default in the whole document: an operation that cannot work without a payload still declares the body optional unless you write `required: true`. Generated clients then make the body argument nullable, and request validators let an empty POST through. - **`content`** — a map from media type to Media Type Object. This field is required. ## The content map Each key is a media type or media type range; each value is a Media Type Object holding `schema`, `example` or `examples`, and (for form and multipart bodies) `encoding`. Keying on media type is what makes one operation able to accept several representations — an `application/json` entry and an `application/xml` entry can even point at the same schema via `$ref`. Ranges are legal — `image/*`, `text/*`, `*/*` — and when a request matches more than one key, only the most specific applies: an explicit `text/plain` entry wins over `text/*`. Note that the media type is the *key*: you do not declare a `Content-Type` header parameter. A header parameter named `Content-Type` is explicitly ignored by the specification precisely because this map already carries that information. ## Form bodies HTML form submissions are request bodies in 3.x, not parameters. `application/x-www-form-urlencoded` takes an object schema whose properties are the form fields; `multipart/form-data` does the same with each property becoming one part. The `encoding` map on the Media Type Object then tunes how individual properties are serialized — for urlencoded bodies it accepts `style`, `explode` and `allowReserved`, mirroring the query-string keywords, and for multipart it accepts `contentType` and `headers`. ## Bodies on GET, HEAD and DELETE OpenAPI notes that `requestBody` is only meaningful for HTTP methods whose semantics define a body, and that for methods where the HTTP specification is vague — `GET`, `HEAD`, `DELETE` — a body is permitted in the document but has no well-defined meaning and should be avoided. Practically: intermediaries, client libraries and server frameworks vary in whether they forward or read such a body at all. When a query genuinely needs a structured payload the usual answer is a POST-based search operation, described with a normal `requestBody`. ## Choosing between a parameter and a body The decision is mechanical rather than stylistic — it follows from where the bytes go. Values that identify the resource belong in the path; values that select, filter or page belong in the query; per-request metadata belongs in headers; the representation being created or replaced belongs in the body. The genuinely debatable case is the large query, and the tradeoff there is cacheability and bookmarkability against URL length limits and expressiveness. ## Reuse A whole request body can be reused: `components.requestBodies` holds named Request Body Objects, referenced with `$ref` from operations. This is the right home for a payload shared across several operations, and it keeps the schema, the examples and the `required` flag together rather than re-deriving them per operation. ## Common defects - Omitting `required: true` on a body the operation cannot work without. - Declaring a `Content-Type` header parameter alongside the content map, which is ignored. - Writing `in: body`, a Swagger 2.0 construct that no 3.x validator accepts. - Declaring one `application/json` entry while the service actually also accepts `application/x-www-form-urlencoded`, so generated clients cannot express the second form. - Putting a body on a `GET` and expecting the whole toolchain to carry it.