io.swagger.annotations

Annotation Type Api

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

Marks a class as a Swagger resource.

By default, Swagger-Core 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 `security` field of the Operation Object.
String	basePath Deprecated.
String	consumes Corresponds to the `consumes` field of the operations under this resource.
String	description Deprecated.
boolean	hidden Hides the operations under this resource.
int	position Deprecated.
String	produces Corresponds to the `produces` field of the operations under this resource.
String	protocols Sets specific protocols (schemes) for the operations under this resource.
String[]	tags A list of tags for API documentation control.
String	value Implicitly sets a tag for the operations, legacy support (read description).

Element Detail

value

public abstract String value

Implicitly sets a tag for the operations, legacy support (read description).

In swagger-core 1.3.X, this was used as the 'path' that is to host the API Declaration of the resource. This is no longer relevant in swagger-core 1.5.X.

If tags() is not used, this value will be used to set the tag for the operations described by this resource. Otherwise, the value will be ignored.

The leading / (if exists) will be removed.

Returns:

tag name for operations under this resource, unless tags() is defined.

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 provided in value().

Returns:

a string array of tag values

Since:

1.5.2-M1

Default:

""

description

@Deprecated
public abstract String description

Deprecated.

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

Returns:

a longer description about this API, no longer used.

Default:

""

basePath

@Deprecated
public abstract String basePath

Deprecated.

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

Returns:

the basePath for this operation, no longer used.

Default:

""

position

@Deprecated
public abstract int position

Deprecated.

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

Returns:

the position of this API in the resource listing, no longer used.

Default:

0

produces

public abstract String produces

Corresponds to the `produces` field of the operations under this resource.

Takes in comma-separated values of content types. For example, "application/json, application/xml" would suggest the operations generate 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 operations under this resource.

Takes in comma-separated values of content types. For example, "application/json, application/xml" would suggest the operations accept 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

Sets specific protocols (schemes) for the operations under this resource.

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 the operations under this 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:

@io.swagger.annotations.Authorization("")

hidden

public abstract boolean hidden

Hides the operations under this resource.

Returns:

true if the api should be hidden from the swagger documentation

Default:

false