Speakeasy Logo
Skip to Content
OpenAPI HubOperations

The Operation Object in OpenAPI

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"

Operation Object Fields

Field
Type
String
Required
Description
A unique identifier for the operation, this must be unique within the document, and is case sensitive. It is recommended to always define an
, but is not required.
Type
Boolean
Required
Description
Whether the operation is deprecated or not. Defaults to
.
Type
String
Required
Description
A short summary of what the operation does. This may contain CommonMark syntax  to provide a rich description.
Type
String
Required
Description
A detailed description of the operation, what it does, and how to use it. This may contain CommonMark syntax  to provide a rich description.
Required
Description
A list of Server Objects that override the servers defined at the document and path levels and apply to this operation.
Required
Description
A list of Security Requirement Objects that override the security requirements defined at the document and path levels and apply to this operation.
Required
Description
Any number of extension fields can be added to the operation object that can be used by tooling and vendors.
Required
Description
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.
Required
Description
The request body for this operation where the HTTP method supports a request body . Otherwise, this field is ignored.
Required
✅
Description
A map of Response Objects that define the possible responses from executing this operation.
Required
Description
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.

Last updated on