io.swagger.annotations

Annotation Type ApiOperation

@Target(value=METHOD)
@Retention(value=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.

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	value Corresponds to the `summary` field of the operation.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Authorization[]	authorizations Corresponds to the `security` field of the Operation Object.
int	code The HTTP status code of the response.
String	consumes Corresponds to the `consumes` field of the operation.
Extension[]	extensions
boolean	hidden Hides the operation from the list of operations.
String	httpMethod Corresponds to the `method` field as the HTTP method used.
String	nickname Corresponds to the `operationId` field.
String	notes Corresponds to the 'notes' field of the operation.
int	position Deprecated.
String	produces Corresponds to the `produces` field of the operation.
String	protocols Sets specific protocols (schemes) for this operation.
Class<?>	response The response type of the operation.
String	responseContainer Declares a container wrapping the response.
ResponseHeader[]	responseHeaders A list of possible headers provided alongside the response.
String	responseReference Specifies a reference to the response type.
String[]	tags A list of tags for API documentation control.

Element Detail

value

public abstract 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

public abstract String notes

Corresponds to the 'notes' field of the operation.

A verbose description of the operation.

Default:

""

tags

public abstract 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

public abstract 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

public abstract String responseContainer

Declares a container wrapping the response.

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

Default:

""

responseReference

public abstract 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

public abstract 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
public abstract int position

Deprecated.

Not used in 1.5.X, kept for legacy support.

Default:

0

nickname

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract boolean hidden

Hides the operation from the list of operations.

Default:

false

responseHeaders

public abstract 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)

code

public abstract int code

The HTTP status code of the response.

The value should be one of the formal HTTP Status Code Definitions.

Default:

200

extensions

public abstract Extension[] extensions

Returns:

an optional array of extensions

Default:

@io.swagger.annotations.Extension(properties=@io.swagger.annotations.ExtensionProperty(name="", value=""))