io.swagger.v3.oas.annotations

Annotation Type Parameter

@Target(value={PARAMETER,METHOD,FIELD,ANNOTATION_TYPE})
 @Retention(value=RUNTIME)
 @Repeatable(value=Parameters.class)
 @Inherited
public @interface Parameter

The annotation may be used on a method parameter to define it as a parameter for the operation, and/or to define additional properties for the Parameter. It can also be used independently in Operation.parameters() or at method level to add a parameter to the operation, even if not bound to any method parameter.

swagger-jaxrs2 reader engine considers this annotation along with JAX-RS annotations, parameter type and context as input to resolve a method parameter into an OpenAPI Operation parameter.

For method parameters bound to the request body, see RequestBody

See Also:

Parameter (OpenAPI specification), RequestBody, Operation, Schema

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	allowEmptyValue When true, allows sending an empty value.
boolean	allowReserved Determines whether the parameter value should allow reserved characters, as defined by RFC3986.
ArraySchema	array The schema of the array that defines this parameter.
Content[]	content The representation of this parameter, for different media types.
boolean	deprecated Specifies that a parameter is deprecated and should be transitioned out of usage.
String	description Additional description data to provide on the purpose of the parameter
String	example Provides an example of the schema.
ExampleObject[]	examples An array of examples of the schema used to show the use of the associated schema.
Explode	explode When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.
Extension[]	extensions The list of optional extensions
boolean	hidden Allows this parameter to be marked as hidden
ParameterIn	in The location of the parameter.
String	name The name of the parameter.
String	ref A reference to a parameter defined in components parameter.
boolean	required Determines whether this parameter is mandatory.
Schema	schema The schema defining the type used for the parameter.
ParameterStyle	style Describes how the parameter value will be serialized depending on the type of the parameter value.

Element Detail

name

public abstract String name

The name of the parameter.

Returns:

the parameter's name

Default:

""

in

public abstract ParameterIn in

The location of the parameter. Possible values are "query", "header", "path" or "cookie". Ignored when empty string.

Returns:

the parameter's location

Default:

io.swagger.v3.oas.annotations.enums.ParameterIn.DEFAULT

description

public abstract String description

Additional description data to provide on the purpose of the parameter

Returns:

the parameter's description

Default:

""

required

public abstract boolean required

Determines whether this parameter is mandatory. If the parameter location is "path", this property is required and its value must be true. Otherwise, the property may be included and its default value is false.

Returns:

whether or not the parameter is required

Default:

false

deprecated

public abstract boolean deprecated

Specifies that a parameter is deprecated and should be transitioned out of usage.

Returns:

whether or not the parameter is deprecated

Default:

false

allowEmptyValue

public abstract boolean allowEmptyValue

When true, allows sending an empty value. If false, the parameter will be considered \"null\" if no value is present. This may create validation errors when the parameter is required.

Returns:

whether or not the parameter allows empty values

Default:

false

style

public abstract ParameterStyle style

Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form. Ignored if the properties content or array are specified.

Returns:

the style of the parameter

Default:

io.swagger.v3.oas.annotations.enums.ParameterStyle.DEFAULT

explode

public abstract Explode explode

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When style is form, the default value is true. For all other styles, the default value is false. Ignored if the properties content or array are specified.

Returns:

whether or not to expand individual array members

Default:

io.swagger.v3.oas.annotations.enums.Explode.DEFAULT

allowReserved

public abstract boolean allowReserved

Determines whether the parameter value should allow reserved characters, as defined by RFC3986. This property only applies to parameters with an in value of query. The default value is false. Ignored if the properties content or array are specified.

Returns:

whether or not the parameter allows reserved characters

Default:

false

schema

public abstract Schema schema

The schema defining the type used for the parameter. Ignored if the properties content or array are specified.

Returns:

the schema of the parameter

Default:

@io.swagger.v3.oas.annotations.media.Schema

array

public abstract ArraySchema array

The schema of the array that defines this parameter. Ignored if the property content is specified.

Returns:

the schema of the array

Default:

@io.swagger.v3.oas.annotations.media.ArraySchema

content

public abstract Content[] content

The representation of this parameter, for different media types.

Returns:

the content of the parameter

Default:

{}

hidden

public abstract boolean hidden

Allows this parameter to be marked as hidden

Returns:

whether or not this parameter is hidden

Default:

false

examples

public abstract ExampleObject[] examples

An array of examples of the schema used to show the use of the associated schema.

Returns:

array of examples of the parameter

Default:

{}

example

public abstract String example

Provides an example of the schema. When associated with a specific media type, the example string shall be parsed by the consumer to be treated as an object or an array. Ignored if the properties examples, content or array are specified.

Returns:

an example of the parameter

Default:

""

extensions

public abstract Extension[] extensions

The list of optional extensions

Returns:

an optional array of extensions

Default:

{}

ref

public abstract String ref

A reference to a parameter defined in components parameter.

Returns:

the reference

Since:

2.0.3

Default:

""