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:

  • 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:
      {}