Package org.eclipse.microprofile.openapi.annotations

Annotation Interface 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:
      {}