com.wordnik.swagger.annotations

Annotation Type ApiOperation

@Target(value=METHOD)
@Retention(value=RUNTIME)
@Inherited
public @interface ApiOperation

Describes an operation or typically a HTTP method against a specific path.

Operations with equivalent paths are grouped in an array in the Api Declaration. 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 `authorizations` field of the operation.
String	consumes Corresponds to the `consumes` field of the operation.
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 `nickname` field.
String	notes Corresponds to the 'notes' field of the operation.
int	position Optional explicit ordering of this API resource in the Resource Listing.
String	produces Corresponds to the `produces` field of the operation.
String	protocols This property is currently not in use.
Class<?>	response The response type of the operation.
String	responseContainer Notes whether the response type is a list of values.
String	tags Currently not implemented in readers, reserved for future use.

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:

""

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

Notes whether the response type is a list of values.

Valid values are "List", "Array" and "Set". "List" and "Array" are regular lists (no difference between them), and "Set" means the list contains unique values only.

Any other value will be ignored.

Default:

""

tags

public abstract String tags

Currently not implemented in readers, reserved for future use.

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

public abstract int position

Optional explicit ordering of this API resource in the Resource Listing.

Default:

0

nickname

public abstract String nickname

Corresponds to the `nickname` field.

The nickname field is used by third-party tools to uniquely identify this operation. In JAX-RS environemnt, this would default to the method name, but can be overridden.

For Servlets, you must specify this field.

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 API Resource 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

This property is currently not in use.

Default:

""

authorizations

public abstract Authorization[] authorizations

Corresponds to the `authorizations` field of the operation.

Takes in a list of the required authorizations for this operation.

See Also:

Authorization

Default:

@com.wordnik.swagger.annotations.Authorization("")

hidden

public abstract boolean hidden

Hides the operation from the list of operations.

Default:

false