1 /**
2  * Copyright 2017 SmartBear Software
3  * <p>
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  * <p>
8  * http://www.apache.org/licenses/LICENSE-2.0
9  * <p>
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package io.swagger.v3.oas.annotations.headers;
18
19 import io.swagger.v3.oas.annotations.media.Schema;
20
21 import java.lang.annotation.Inherited;
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.RetentionPolicy;
24 import java.lang.annotation.Target;
25
26 /**
27  * The annotation may be used to add one or more headers to the definition of a response or as attribute of content
28  * 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()}.
29  * <p>Please note that request headers are defined as Header {@link io.swagger.v3.oas.annotations.Parameter}.</p>
30  *
31  * @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>
32  * @see io.swagger.v3.oas.annotations.responses.ApiResponse
33  * @see io.swagger.v3.oas.annotations.Parameter
34  * @see io.swagger.v3.oas.annotations.media.Encoding
35  **/
36 @Target({})
37 @Retention(RetentionPolicy.RUNTIME)
38 @Inherited
39 public @interface Header {
40     /**
41      * Required: The name of the header. The name is only used as the key to store this header in a map.
42      *
43      * @return the header's name
44      **/
45     String name();
46
47     /**
48      * Additional description data to provide on the purpose of the header
49      *
50      * @return the header's description
51      **/
52     String description() default "";
53
54     /**
55      * The schema defining the type used for the header. Ignored if the properties content or array are specified.
56      *
57      * @return the schema of the header
58      **/
59     Schema schema() default @Schema();
60
61     /**
62      * Determines whether this header is mandatory. The property may be included and its default value is false.
63      *
64      * @return whether or not the header is required
65      **/
66     boolean required() default false;
67
68     /**
69      * Specifies that a header is deprecated and should be transitioned out of usage.
70      *
71      * @return whether or not the header is deprecated
72      **/
73     boolean deprecated() default false;
74
75     /**
76      * A reference to a header defined in components headers.
77      *
78      * @since 2.0.3
79      * @return the reference
80      **/
81     String ref() default "";
82
83 }
84