Package io.swagger.annotations

Annotation Type ApiParam

@Target({PARAMETER,METHOD,FIELD})
@Retention(RUNTIME)
public @interface ApiParam

Adds additional meta-data for operation parameters.

This annotation can be used only in combination of JAX-RS 1.x/2.x annotations.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	access	Allows for filtering a parameter from the API documentation.
String	allowableValues	Limits the acceptable values for this parameter.
boolean	allowEmptyValue	Adds the ability to set a format as empty
boolean	allowMultiple	Specifies whether the parameter can accept multiple values by having multiple occurrences.
String	collectionFormat	adds ability to override collectionFormat with `array` types
String	defaultValue	Describes the default value for the parameter.
String	example	a single example for non-body type parameters
Example	examples	Examples for the parameter.
String	format	Adds the ability to provide a custom format
boolean	hidden	Hides the parameter from the list of parameters.
String	name	The parameter name.
boolean	readOnly	adds ability to be designated as read only.
boolean	required	Specifies if the parameter is required or not.
String	type	Adds the ability to override the detected type
String	value	A brief description of the parameter.

Element Detail

name

String name

The parameter name.

The name of the parameter will be derived from the field/method/parameter name, however you can override it.

Path parameters must always be named as the path section they represent.

Default:

""

value

String value

A brief description of the parameter.

Default:

""

defaultValue

String defaultValue

Describes the default value for the parameter.

If the parameter is annotated with JAX-RS's @DefaultValue, that value would be used, but can be overridden by setting this property.

Default:

""

allowableValues

String allowableValues

Limits the acceptable values for this parameter.

There are three ways to describe the allowable values:

1. To set a list of values, provide a comma-separated list. For example: first, second, third.
2. To set a range of values, start the value with "range", and surrounding by square brackets include the minimum and maximum values, or round brackets for exclusive minimum and maximum values. For example: range[1, 5], range(1, 5), range[1, 5).
3. To set a minimum/maximum value, use the same format for range but use "infinity" or "-infinity" as the second value. For example, range[1, infinity] means the minimum allowable value of this parameter is 1.

Default:

""

required

boolean required

Specifies if the parameter is required or not.

Path parameters will always be set as required, whether you set this property or not.

Default:

false

access

String access

Allows for filtering a parameter from the API documentation.

See io.swagger.core.filter.SwaggerSpecFilter for further details.

Default:

""

allowMultiple

boolean allowMultiple

Specifies whether the parameter can accept multiple values by having multiple occurrences.

Default:

false

hidden

boolean hidden

Hides the parameter from the list of parameters.

Default:

false

example

String example

a single example for non-body type parameters

Returns:

Since:

1.5.4

Default:

""

examples

Example examples

Examples for the parameter. Applies only to BodyParameters

Returns:

Since:

1.5.4

Default:

@io.swagger.annotations.Example({@io.swagger.annotations.ExampleProperty(mediaType="", value="")})

type

String type

Adds the ability to override the detected type

Returns:

Since:

1.5.11

Default:

""

format

String format

Adds the ability to provide a custom format

Returns:

Since:

1.5.11

Default:

""

allowEmptyValue

boolean allowEmptyValue

Adds the ability to set a format as empty

Returns:

Since:

1.5.11

Default:

false

readOnly

boolean readOnly

adds ability to be designated as read only.

Since:

1.5.11

Default:

false

collectionFormat

String collectionFormat

adds ability to override collectionFormat with `array` types

Since:

1.5.11

Default:

""