1 package io.swagger.v3.oas.annotations.headers;
2
3 import io.swagger.v3.oas.annotations.media.Schema;
4
5 import java.lang.annotation.Inherited;
6 import java.lang.annotation.Retention;
7 import java.lang.annotation.RetentionPolicy;
8 import java.lang.annotation.Target;
9
10 /**
11  * The annotation may be used to add one or more headers to the definition of a response or as attribute of content
12  * encoding by defining it as field {@link io.swagger.v3.oas.annotations.responses.ApiResponse#headers()} or {@link io.swagger.v3.oas.annotations.media.Content#encoding()}.
13  * <p>Please note that request headers are defined as Header {@link io.swagger.v3.oas.annotations.Parameter}.</p>
14  *
15  * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#headerObject">Header (OpenAPI specification)</a>
16  * @see io.swagger.v3.oas.annotations.responses.ApiResponse
17  * @see io.swagger.v3.oas.annotations.Parameter
18  * @see io.swagger.v3.oas.annotations.media.Encoding
19  **/
20 @Target({})
21 @Retention(RetentionPolicy.RUNTIME)
22 @Inherited
23 public @interface Header {
24     /**
25      * Required: The name of the header. The name is only used as the key to store this header in a map.
26      *
27      * @return the header's name
28      **/
29     String name();
30
31     /**
32      * Additional description data to provide on the purpose of the header
33      *
34      * @return the header's description
35      **/
36     String description() default "";
37
38     /**
39      * The schema defining the type used for the header. Ignored if the properties content or array are specified.
40      *
41      * @return the schema of the header
42      **/
43     Schema schema() default @Schema();
44
45     /**
46      * Determines whether this header is mandatory. The property may be included and its default value is false.
47      *
48      * @return whether or not the header is required
49      **/
50     boolean required() default false;
51
52     /**
53      * Specifies that a header is deprecated and should be transitioned out of usage.
54      *
55      * @return whether or not the header is deprecated
56      **/
57     boolean deprecated() default false;
58
59     /**
60      * A reference to a header defined in components headers.
61      *
62      * @since 2.0.3
63      * @return the reference
64      **/
65     String ref() default "";
66
67 }
68