Module org.eclipse.microprofile.openapi
Package org.eclipse.microprofile.openapi.annotations.headers

# Annotation Type Header

@Target({}) @Retention(RUNTIME) @Inherited public @interface Header
Describes a single header object.

Note that although the {@linkplain #org.eclipse.microprofile.openapi.models.headers.Header header} model contains a `content` property, modeling that information using annotations is not possible because the content annotation's `encoding` references this annotation, a cycle disallowed by the Java language.

See Also:
  - OpenAPI Specification Header Object

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
Description
`boolean`
`allowEmptyValue`
Deprecated, for removal: This API element is subject to removal in a future version.
The OpenAPI specification states that `allowEmptyValue` is only valid for `query` parameters.
`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`
Example of the header's potential value.
`ExampleObject[]`
`examples`
Examples of the header's potential value.
`Extension[]`
`extensions`
List of extensions to be added to the `Header` model corresponding to the containing annotation.
`String`
`name`
The name of the header.
`String`
`ref`
Reference value to a Header object.
`boolean`
`required`
Determines whether this header is mandatory.
`Schema`
`schema`
The schema defining the type used for the header.

## Element Details

### name

String name
The name of the header. The name is only used as the key to add this header to a map.

It is a REQUIRED property unless this is only a reference to a header instance.

When the header is defined within `Components`, the name will be used as the key to add this header to the 'headers' map for reuse.

Returns:
  this header's name

Default:
  ""

### 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:
  @org.eclipse.microprofile.openapi.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

### allowEmptyValue

@Deprecated(since="4.2", forRemoval=true) boolean allowEmptyValue
Deprecated, for removal: This API element is subject to removal in a future version.
The OpenAPI specification states that `allowEmptyValue` is only valid for `query` parameters. As the `Header` model is a specialized `Parameter`, this attribute is not valid and should not be used. Removal of this property is planned for the next major release of MicroProfile OpenAPI.
When true, allows sending an empty value. If false, the header will be considered \"null\" if no value is present. This may create validation errors when the header is required.

Returns:
  whether or not the header allows empty values

Default:
  false

### ref

String ref
Reference value to a Header object.

This property provides a reference to an object defined elsewhere. This property may be used with `description()` but is mutually exclusive with all other properties. If properties other than `description` are defined in addition to the `ref` property then the result is undefined.

Returns:
  reference to a header

Default:
  ""

### extensions

Extension[] extensions
List of extensions to be added to the `Header` model corresponding to the containing annotation.

Returns:
  array of extensions
Since:
  3.1

Default:
  {}

### example

String example
Example of the header's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL override the example provided by the schema.

If the media type associated with the example allows parsing into an object, it may be converted from a string.

Returns:
  an example of the header
Since:
  4.2

Default:
  ""

### examples

ExampleObject[] examples
Examples of the header's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a schema that contains an example, the `examples` value SHALL override the example provided by the schema.

Returns:
  the list of examples for this header
Since:
  4.2

Default:
  {}