Package io.swagger.annotations

Annotation Type ApiOperation

  • @Target({METHOD,TYPE})
@Retention(RUNTIME)
public @interface ApiOperation
    Describes an operation or typically a HTTP method against a specific path.

    Operations with equivalent paths are grouped in a single Operation Object. A combination of a HTTP method and a path creates a unique operation.

    • Element Detail

      • value

        String value
        Corresponds to the `summary` field of the operation.

        Provides a brief description of this operation. Should be 120 characters or less for proper visibility in Swagger-UI.

      • notes

        String notes
        Corresponds to the 'notes' field of the operation.

        A verbose description of the operation.

        Default:
        ""

      • tags

        String[] tags
        A list of tags for API documentation control.

        Tags can be used for logical grouping of operations by resources or any other qualifier. A non-empty value will override the value received from Api.value() or Api.tags() for this operation.

        Since:
        1.5.2-M1
        Default:
        {""}

      • response

        Class<?> response
        The response type of the operation.

        In JAX-RS applications, the return type of the method would automatically be used, unless it is javax.ws.rs.core.Response. In that case, the operation return type would default to `void` as the actual response type cannot be known.

        Setting this property would override any automatically-derived data type.

        If the value used is a class representing a primitive (Integer, Long, ...) the corresponding primitive type will be used.

        Default:
        java.lang.Void.class

      • responseContainer

        String responseContainer
        Declares a container wrapping the response.

        Valid values are "List", "Set" or "Map". Any other value will be ignored.

        Default:
        ""

      • responseReference

        String responseReference
        Specifies a reference to the response type. The specified reference can be either local or remote and will be used as-is, and will override any specified response() class.
        Default:
        ""

      • httpMethod

        String httpMethod
        Corresponds to the `method` field as the HTTP method used.

        If not stated, in JAX-RS applications, the following JAX-RS annotations would be scanned and used: @GET, @HEAD, @POST, @PUT, @DELETE and @OPTIONS. Note that even though not part of the JAX-RS specification, if you create and use the @PATCH annotation, it will also be parsed and used. If the httpMethod property is set, it will override the JAX-RS annotation.

        For Servlets, you must specify the HTTP method manually.

        Acceptable values are "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH".

        Default:
        ""

      • position

        @Deprecated
int position
        Deprecated.
        Not used in 1.5.X, kept for legacy support.
        Default:
        0

      • nickname

        String nickname
        Corresponds to the `operationId` field.

        The operationId is used by third-party tools to uniquely identify this operation. In Swagger 2.0, this is no longer mandatory and if not provided will remain empty.

        Default:
        ""

      • produces

        String produces
        Corresponds to the `produces` field of the operation.

        Takes in comma-separated values of content types. For example, "application/json, application/xml" would suggest this operation generates JSON and XML output.

        For JAX-RS resources, this would automatically take the value of the @Produces annotation if such exists. It can also be used to override the @Produces values for the Swagger documentation.

        Default:
        ""

      • consumes

        String consumes
        Corresponds to the `consumes` field of the operation.

        Takes in comma-separated values of content types. For example, "application/json, application/xml" would suggest this API Resource accepts JSON and XML input.

        For JAX-RS resources, this would automatically take the value of the @Consumes annotation if such exists. It can also be used to override the @Consumes values for the Swagger documentation.

        Default:
        ""

      • protocols

        String protocols
        Sets specific protocols (schemes) for this operation.

        Comma-separated values of the available protocols. Possible values: http, https, ws, wss.

        Returns:
        the protocols supported by the operations under the resource.
        Default:
        ""

      • authorizations

        Authorization[] authorizations
        Corresponds to the `security` field of the Operation Object.

        Takes in a list of the authorizations (security requirements) for this operation.

        Returns:
        an array of authorizations required by the server, or a single, empty authorization value if not set.
        See Also:
        Authorization
        Default:
        {@io.swagger.annotations.Authorization("")}

      • hidden

        boolean hidden
        Hides the operation from the list of operations.
        Default:
        false

      • responseHeaders

        ResponseHeader[] responseHeaders
        A list of possible headers provided alongside the response.
        Returns:
        a list of response headers.
        Default:
        {@io.swagger.annotations.ResponseHeader(name="", response=java.lang.Void.class)}

      • extensions

        Extension[] extensions
        Returns:
        an optional array of extensions
        Default:
        {@io.swagger.annotations.Extension(properties={@io.swagger.annotations.ExtensionProperty(name="", value="")})}

      • ignoreJsonView

        boolean ignoreJsonView
        Ignores JsonView annotations while resolving operations and types. For backward compatibility
        Default:
        false