What is the OpenAPI Operation Object?

It describes a single API operation on a path — typically one HTTP method such as GET or POST. It lives under a Path Item Object keyed by the method name and holds the parameters, request body, responses and metadata for that call.

Which Operation fields are required?

Only responses is required; it must contain at least one response. Every other field — including parameters, requestBody, tags and security — is optional and can be omitted when not needed.

What changed between OpenAPI 3.0 and 3.1?

3.1 aligns the schema dialect with JSON Schema 2020-12, so Operation-level schemas gain full JSON Schema keywords. The Operation Object field set itself is essentially unchanged; requestBody, callbacks and the deprecated flag all carry over.

Where does the operationId field matter?

operationId is an optional but recommended unique string identifying the operation. Code generators use it to name client methods, and links reference it. It must be unique across the whole document.

Does this reference call any API?

No. The field list and search run locally in your browser. Nothing is transmitted.

OpenAPI Operation Object Fields

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

The OpenAPI 3.1 Operation Object

In an OpenAPI document, each HTTP method under a path is an Operation Object. It bundles the parameters, request body, possible responses and metadata for one call. This reference lists every field of the 3.1 Operation Object with its JSON type and requirement, plus a live search.

How it works

An Operation sits inside a Path Item, keyed by the lowercase method name:

paths:
  /pets/{id}:
    get:
      operationId: getPet
      tags: [pets]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: A pet

Only the responses field is required. The parameters array is merged with any path-level parameters; requestBody replaces the older body parameter from Swagger 2.0; and callbacks define out-of-band webhooks the API may send.

Tips and notes

Set deprecated: true to flag an operation for removal without deleting it.
Give every operation a unique operationId so generators produce clean names.
An operation-level security array overrides the document-level default.
servers on an operation overrides the path and root server lists.