com.wordnik.swagger.annotations

Annotation Type Api

@Target(value=TYPE)
@Retention(value=RUNTIME)
@Inherited
public @interface Api

Marks a class as a Swagger resource.

The resource affects both the root document of Swagger, the Resource Listing, and the API Declaration of that specific resource.

Swagger will only include and introspect only classes that are annotated with @Api and will ignore other resources (JAX-RS endpoints, Servlets and so on).

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Authorization[]	authorizations Corresponds to the `authorizations` field of the API Declaration.
String	basePath Deprecated.
String	consumes Corresponds to the `consumes` field of the API Declaration.
String	description Corresponds to the `description` field of the Resource Listing API operation.
boolean	hidden Hides the api.
int	position Deprecated.
String	produces Corresponds to the `produces` field of the API Declaration.
String	protocols This property is currently not in use.
String[]	tags A list of tags for API documentation control.
String	value The 'path' that is going to be used to host the API Declaration of the resource.

Element Detail

value

public abstract String value

The 'path' that is going to be used to host the API Declaration of the resource.

For JAX-RS resources, this would normally have the same value as the @Path on the resource, but can be any other value as well. It will serve as the path where the documentation is hosted.

For Servlets, this path has to be the path serving the Servlet.

If the value isn't preceded with a slash, one would be added to it.

Returns:

the document location value, or empty string if not set

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.

Returns:

a string array of tag values

Since:

1.5.2

Default:

""

description

public abstract String description

Corresponds to the `description` field of the Resource Listing API operation.

This should be a short description of the resource.

Returns:

a longer description about this API

Default:

""

basePath

@Deprecated
public abstract String basePath

Deprecated.

Corresponds to the `basePath` field of the API Declaration.

The `basePath` is derived automatically by Swagger. This property allows overriding the default value if needed. for swagger 2.0 specifications, this value is no longer supported

Returns:

the basePath for this operation

Since:

1.3.7

Default:

""

position

@Deprecated
public abstract int position

Deprecated.

Optional explicit ordering of this API resource in the Resource Listing. As of swagger-spec 2.0, this value is no longer used

Returns:

the position of this API in the resource listing

Default:

0

produces

public abstract String produces

Corresponds to the `produces` field of the API Declaration.

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.

Returns:

the supported media types supported by the server, or an empty string if not set

Default:

""

consumes

public abstract String consumes

Corresponds to the `consumes` field of the API Declaration.

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.

Returns:

the consumes value, or empty string if not set

Default:

""

protocols

public abstract String protocols

This property is currently not in use.

Returns:

the protocols supported by the server

Default:

""

authorizations

public abstract Authorization[] authorizations

Corresponds to the `authorizations` field of the API Declaration.

Takes in a list of the required authorizations for this API Resource. This may be overridden by specific operations.

Returns:

an array of authorizations required by the server, or a single, empty authorization value if not set

See Also:

Authorization

Default:

@com.wordnik.swagger.annotations.Authorization(value="", type="")

hidden

public abstract boolean hidden

Hides the api.

Returns:

true if the api should be hidden from the swagger documentation

Since:

1.3.8

Default:

false