Package io.swagger.v3.oas.annotations

Annotation Type Operation

  • @Target({METHOD,ANNOTATION_TYPE})
@Retention(RUNTIME)
@Inherited
public @interface Operation
    The annotation may be used to define a resource method as an OpenAPI Operation, and/or to define additional properties for the Operation.

    Note: swagger-jaxrs2 reader engine includes by default also methods of scanned resources which are not annotated with @Operation, as long as a jax-rs @Path is defined at class and/or method level, together with the http method annotation (@GET, @POST, etc).

    This behaviour is controlled by configuration property `scanAllResources` which defaults to true. By setting this flag to false only @Operation annotated methods are considered.

    The following fields can also alternatively be defined at method level (as repeatable annotations in case of arrays), in this case method level annotations take precedence over @Operation annotation fields:

    See Also:
    Operation (OpenAPI specification)

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      boolean deprecated
      Allows an operation to be marked as deprecated.
      String description
      A verbose description of the operation.
      Extension[] extensions
      The list of optional extensions
      ExternalDocumentation externalDocs
      Additional external documentation for this operation.
      boolean hidden
      Allows this operation to be marked as hidden
      boolean ignoreJsonView
      Ignores JsonView annotations while resolving operations and types.
      String method
      The HTTP method for this operation.
      String operationId
      The operationId is used by third-party tools to uniquely identify this operation.
      Parameter[] parameters
      An optional array of parameters which will be added to any automatically detected parameters in the method itself.
      RequestBody requestBody
      Request body associated to the operation.
      ApiResponse[] responses
      The list of possible responses as they are returned from executing this operation.
      SecurityRequirement[] security
      A declaration of which security mechanisms can be used for this operation.
      Server[] servers
      An alternative server array to service this operation.
      String summary
      Provides a brief description of this operation.
      String[] tags
      Tags can be used for logical grouping of operations by resources or any other qualifier.

    • Element Detail

      • method

        String method
        The HTTP method for this operation.
        Returns:
        the HTTP method of this operation
        Default:
        ""

      • tags

        String[] tags
        Tags can be used for logical grouping of operations by resources or any other qualifier.
        Returns:
        the list of tags associated with this operation
        Default:
        {}

      • summary

        String summary
        Provides a brief description of this operation. Should be 120 characters or less for proper visibility in Swagger-UI.
        Returns:
        a summary of this operation
        Default:
        ""

      • description

        String description
        A verbose description of the operation.
        Returns:
        a description of this operation
        Default:
        ""

      • requestBody

        RequestBody requestBody
        Request body associated to the operation.
        Returns:
        a request body.
        Default:
        @io.swagger.v3.oas.annotations.parameters.RequestBody

      • externalDocs

        ExternalDocumentation externalDocs
        Additional external documentation for this operation.
        Returns:
        additional documentation about this operation
        Default:
        @io.swagger.v3.oas.annotations.ExternalDocumentation

      • operationId

        String operationId
        The operationId is used by third-party tools to uniquely identify this operation.
        Returns:
        the ID of this operation
        Default:
        ""

      • parameters

        Parameter[] parameters
        An optional array of parameters which will be added to any automatically detected parameters in the method itself.
        Returns:
        the list of parameters for this operation
        Default:
        {}

      • responses

        ApiResponse[] responses
        The list of possible responses as they are returned from executing this operation.
        Returns:
        the list of responses for this operation
        Default:
        {}

      • deprecated

        boolean deprecated
        Allows an operation to be marked as deprecated. Alternatively use the @Deprecated annotation
        Returns:
        whether or not this operation is deprecated
        Default:
        false

      • security

        SecurityRequirement[] security
        A declaration of which security mechanisms can be used for this operation.
        Returns:
        the array of security requirements for this Operation
        Default:
        {}

      • servers

        Server[] servers
        An alternative server array to service this operation.
        Returns:
        the list of servers hosting this operation
        Default:
        {}

      • extensions

        Extension[] extensions
        The list of optional extensions
        Returns:
        an optional array of extensions
        Default:
        {}

      • hidden

        boolean hidden
        Allows this operation to be marked as hidden
        Returns:
        whether or not this operation is hidden
        Default:
        false

      • ignoreJsonView

        boolean ignoreJsonView
        Ignores JsonView annotations while resolving operations and types.
        Returns:
        whether or not to ignore JsonView annotations
        Default:
        false