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).

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	value The 'path' that is going to be used to host the API Declaration of the resource.

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 Corresponds to the `basePath` field of the API Declaration.
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 Optional explicit ordering of this API resource in the Resource Listing.
String	produces Corresponds to the `produces` field of the API Declaration.
String	protocols This property is currently not in use.

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.

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.

Default:

""

basePath

public abstract String basePath

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.

Since:

1.3.7

Default:

""

position

public abstract int position

Optional explicit ordering of this API resource 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.

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.

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 API Declaration.

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

See Also:

Authorization

Default:

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

hidden

public abstract boolean hidden

Hides the api.

Since:

1.3.8

Default:

false