OpenAPI Parameters Object

In OpenAPI, parameters formally describe values supplied with an operation through locations such as the path, query string, headers, or cookies. Each parameter declares details such as its name, location, required status, and schema.

An OpenAPI Parameter Object describes one input value associated with an API operation. Its `name` identifies the value and `in` specifies where the value is transmitted: `path`, `query`, `header`, or `cookie`.

For example, `/users/{id}` can define an `id` path parameter, while `/users?active=true` can define an `active` query parameter. A parameter's `schema` describes its data type and constraints, such as `string`, `integer`, or an allowed value set.

Path parameters are always required because they are part of the URL template. Query, header, and cookie parameters can be optional or required depending on the API contract. The `required` field therefore has different practical importance depending on the parameter location.

Parameters describe individual request values; they do not normally describe a JSON request body. A request body is represented separately with OpenAPI's `requestBody` field.

In Java backend development, this distinction maps naturally to common HTTP concepts such as path variables, query parameters, request headers, and cookies. OpenAPI documents these inputs so tools can generate documentation, clients, validation behavior, or server stubs from the contract.

Key points

• A Parameter Object represents one API input value.
• `in` identifies the location: `path`, `query`, `header`, or `cookie`.
• Path parameters must be marked `required: true`.
• `schema` describes the parameter's type and constraints.
• Request bodies are described with `requestBody`, not a Parameter Object.

Interview questions

What is an OpenAPI Parameter Object?

It describes a single value supplied as part of an HTTP request. The `name` identifies the value and `in` specifies whether it comes from the path, query string, header, or cookie. Other fields can describe whether it is required and what schema it follows.

Why must a path parameter be required?

A path parameter is part of the URL template itself, so the operation cannot match that template without a value for the parameter. For example, `/users/{id}` requires an `id` value. OpenAPI therefore requires path parameters to have `required: true`.

What are the valid locations for OpenAPI parameters?

The standard parameter locations are `path`, `query`, `header`, and `cookie`. The `in` field selects exactly one of these locations. A JSON payload is not another parameter location; it is described using `requestBody`.

How would you document a Java endpoint with both a path variable and a query parameter?

I would create two Parameter Objects under the operation's `parameters` list. The path variable would use `in: path`, have the same name as the URL-template variable, and be required. The query value would use `in: query` and can be optional unless the API contract requires it. Each parameter would have a schema matching the Java endpoint's expected type.