Package io.swagger.v3.oas.annotations.headers

Annotation Type Header

@Target({})
@Retention(RUNTIME)
@Inherited
public @interface Header

The annotation may be used to add one or more headers to the definition of a response or as attribute of content encoding by defining it as field ApiResponse.headers() or Content.encoding().

Please note that request headers are defined as Header Parameter.

See Also:

Header (OpenAPI specification), ApiResponse, Parameter, Encoding

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	name	Required: The name of the header.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
ArraySchema	array	The schema of the array that defines this header.
boolean	deprecated	Specifies that a header is deprecated and should be transitioned out of usage.
String	description	Additional description data to provide on the purpose of the header
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.
boolean	hidden	Allows this header to be marked as hidden
String	ref	A reference to a header defined in components headers.
boolean	required	Determines whether this header is mandatory.
Schema	schema	The schema defining the type used for the header.

Element Detail

name

String name

Required: The name of the header. The name is only used as the key to store this header in a map.

Returns:

the header's name

description

String description

Additional description data to provide on the purpose of the header

Returns:

the header's description

Default:

""

schema

Schema schema

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

Returns:

the schema of the header

Default:

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

required

boolean required

Determines whether this header is mandatory. The property may be included and its default value is false.

Returns:

whether or not the header is required

Default:

false

deprecated

boolean deprecated

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

Returns:

whether or not the header is deprecated

Default:

false

ref

String ref

A reference to a header defined in components headers.

Returns:

the reference

Since:

2.0.3

Default:

""

explode

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

hidden

boolean hidden

Allows this header to be marked as hidden

Returns:

whether or not this header is hidden

Default:

false

example

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 header

Default:

""

examples

ExampleObject[] examples

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

Returns:

array of examples of the header

Default:

{}

array

ArraySchema array

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

Returns:

the schema of the array

Default:

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