Module org.eclipse.microprofile.openapi
Package org.eclipse.microprofile.openapi.annotations

# Annotation Type PathItemOperation

@Target({}) @Retention(RUNTIME) public @interface PathItemOperation
Describes an Operation

This annotation is only used for operations defined under a `PathItem`. For operations provided by the API itself, it's more common to use the `Operation` annotation applied to a Jakarta REST resource method instead.

Since:
  4.0

## Required Element Summary

Required Elements
Modifier and Type
Required Element
Description
`String`
`method`
The HTTP method for this operation.

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
Description
`Callback[]`
`callbacks`
A list of possible out-of-band callbacks related to this operation.
`boolean`
`deprecated`
Allows an operation to be marked as deprecated
`String`
`description`
A verbose description of the operation behavior.
`Extension[]`
`extensions`
List of extensions to be added to the `Operation` model corresponding to the containing annotation.
`ExternalDocumentation`
`externalDocs`
Additional external documentation for this operation.
`String`
`operationId`
Unique string used to identify the operation.
`Parameter[]`
`parameters`
An array of parameters applicable for this operation.
`RequestBody`
`requestBody`
The request body for this operation.
`APIResponse[]`
`responses`
The list of possible responses that can be returned when executing this operation.
`SecurityRequirement[]`
`security`
A declaration of which security mechanisms can be used for this callback operation.
`SecurityRequirementsSet[]`
`securitySets`
A declaration of which security mechanisms can be used for this callback operation.
`Server[]`
`servers`
A list of servers to be used for this operation, overriding those defined for the parent path item or for the whole API.
`String`
`summary`
Provides a brief description of what this operation does.
`Tag[]`
`tags`
The tags which apply to this operation.

## Element Details

### method

String method
The HTTP method for this operation.

Returns:
  the HTTP method of this operation

### tags

Tag[] tags
The tags which apply to this operation.

Returns:
  the list of tags

Default:
  {}

### summary

String summary
Provides a brief description of what this operation does.

Returns:
  a summary of this operation

Default:
  ""

### description

String description
A verbose description of the operation behavior. CommonMark syntax MAY be used for rich text representation.

Returns:
  a description of this operation

Default:
  ""

### externalDocs

ExternalDocumentation externalDocs
Additional external documentation for this operation.

Returns:
  external documentation associated with this operation instance

Default:
  @org.eclipse.microprofile.openapi.annotations.ExternalDocumentation

### operationId

String operationId
Unique string used to identify the operation. The id MUST be unique among all operations described in the API.

Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.

Returns:
  the ID of this operation

Default:
  ""

### parameters

Parameter[] parameters
An array of parameters applicable for this operation.

The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location.

Returns:
  the list of parameters for this operation

Default:
  {}

### requestBody

RequestBody requestBody
The request body for this operation.

Returns:
  the request body of this operation

Default:
  @org.eclipse.microprofile.openapi.annotations.parameters.RequestBody

### responses

APIResponse[] responses
The list of possible responses that can be returned when executing this operation.

Returns:
  the list of responses for this operation

Default:
  {}

### callbacks

Callback[] callbacks
A list of possible out-of-band callbacks related to this operation. Each entry represents a set of requests that may be initiated by the API provided and an expression, evaluated at runtime, that identifies the URL used to make those requests.

Returns:
  the list of callbacks for this operation

Default:
  {}

### deprecated

boolean deprecated
Allows an operation to be marked as deprecated

Consumers SHOULD refrain from usage of a deprecated operation.

Returns:
  whether or not this operation is deprecated

Default:
  false

### security

SecurityRequirement[] security
A declaration of which security mechanisms can be used for this callback operation. Only one of the security requirement objects need to be satisfied to authorize a request.

Adding a `SecurityRequirement` to this array is equivalent to adding a `SecurityRequirementsSet` containing a single `SecurityRequirement` to `securitySets()`.

This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.

Returns:
  the list of security mechanisms for this operation

Default:
  {}

### securitySets

SecurityRequirementsSet[] securitySets
A declaration of which security mechanisms can be used for this callback operation. All of the security requirements within any one of the sets needs needs to be satisfied to authorize a request.

This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.

Including an empty set within this list indicates that the other requirements are optional.

Returns:
  the list of security mechanisms for this operation

Default:
  {}

### servers

Server[] servers
A list of servers to be used for this operation, overriding those defined for the parent path item or for the whole API.

Returns:
  the list of servers

Default:
  {}

### extensions

Extension[] extensions
List of extensions to be added to the `Operation` model corresponding to the containing annotation.

Returns:
  array of extensions

Default:
  {}