The OpenAPI Operation Object
An operation object describes a single API operation within a path, including all its possible inputs and outputs and the configuration required to make a successful request.
Each operation object corresponds to an HTTP verb, such as get
, post
, or delete
.
Example:
paths: /drinks: get: # The Operation Object operationId: listDrinks summary: Get a list of drinks. description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information. security: - {} tags: - drinks parameters: - name: type in: query description: The type of drink to filter by. If not provided all drinks will be returned. required: false schema: $ref: "#/components/schemas/DrinkType" responses: "200": description: A list of drinks. content: application/json: schema: type: array items: $ref: "#/components/schemas/Drink"
Field | Type | Required | Description |
---|---|---|---|
operationId | String | A unique identifier for the operation, this must be unique within the document, and is case sensitive. It is recommended to always define an operationId , but is not required. | |
deprecated | Boolean | Whether the operation is deprecated or not. Defaults to false . | |
summary | String | A short summary of what the operation does. This may contain CommonMark syntax (opens in a new tab) to provide a rich description. | |
description | String | A detailed description of the operation, what it does, and how to use it. This may contain CommonMark syntax (opens in a new tab) to provide a rich description. | |
servers | Servers | A list of Server Objects that override the servers defined at the document and path levels and apply to this operation. | |
security | Security | A list of Security Requirement Objects that override the security requirements defined at the document and path levels and apply to this operation. | |
x-* | Extensions | Any number of extension fields can be added to the operation object that can be used by tooling and vendors. | |
parameters | Parameters | A list of Parameter Objects that are available to this operation. The parameters defined here merge with any defined at the path level, overriding any duplicates. | |
requestBody | Request Body Object | The request body for this operation where the HTTP method supports a request body (opens in a new tab). Otherwise, this field is ignored. | |
responses | Responses | ✅ | A map of Response Objects that define the possible responses from executing this operation. |
callbacks | Callbacks | A map of Callback Objects that define possible callbacks that may be executed as a result of this operation. |
The above order of fields is recommended for defining the fields in the document to help set the stage for the operation and provide a clear understanding of what it does.