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;
18
19 import io.swagger.v3.oas.annotations.enums.Explode;
20 import io.swagger.v3.oas.annotations.enums.ParameterIn;
21 import io.swagger.v3.oas.annotations.enums.ParameterStyle;
22 import io.swagger.v3.oas.annotations.extensions.Extension;
23 import io.swagger.v3.oas.annotations.media.ArraySchema;
24 import io.swagger.v3.oas.annotations.media.Content;
25 import io.swagger.v3.oas.annotations.media.ExampleObject;
26 import io.swagger.v3.oas.annotations.media.Schema;
27
28 import java.lang.annotation.Inherited;
29 import java.lang.annotation.Repeatable;
30 import java.lang.annotation.Retention;
31 import java.lang.annotation.RetentionPolicy;
32 import java.lang.annotation.Target;
33
34 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
35 import static java.lang.annotation.ElementType.FIELD;
36 import static java.lang.annotation.ElementType.METHOD;
37 import static java.lang.annotation.ElementType.PARAMETER;
38
39 /**
40 * The annotation may be used on a method parameter to define it as a parameter for the operation, and/or to define
41 * additional properties for the Parameter. It can also be used independently in {@link Operation#parameters()} or at
42 * method level to add a parameter to the operation, even if not bound to any method parameter.
43 *
44 * <p>swagger-jaxrs2 reader engine considers this annotation along with JAX-RS annotations, parameter type and context
45 * as input to resolve a method parameter into an OpenAPI Operation parameter.</p>
46 *
47 * <p>For method parameters bound to the request body, see {@link io.swagger.v3.oas.annotations.parameters.RequestBody}</p>
48 *
49 * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#parameterObject">Parameter (OpenAPI specification)</a>
50 * @see io.swagger.v3.oas.annotations.parameters.RequestBody
51 * @see Operation
52 * @see Schema
53 **/
54 @Target({PARAMETER, METHOD, FIELD, ANNOTATION_TYPE})
55 @Retention(RetentionPolicy.RUNTIME)
56 @Repeatable(Parameters.class)
57 @Inherited
58 public @interface Parameter {
59 /**
60 * The name of the parameter.
61 *
62 * @return the parameter's name
63 **/
64 String name() default "";
65
66 /**
67 * The location of the parameter. Possible values are "query", "header", "path" or "cookie". Ignored when empty string.
68 *
69 * @return the parameter's location
70 **/
71 ParameterIn in() default ParameterIn.DEFAULT;
72
73 /**
74 * Additional description data to provide on the purpose of the parameter
75 *
76 * @return the parameter's description
77 **/
78 String description() default "";
79
80 /**
81 * Determines whether this parameter is mandatory. If the parameter location is "path", this property is required and its value must be true. Otherwise, the property may be included and its default value is false.
82 *
83 * @return whether or not the parameter is required
84 **/
85 boolean required() default false;
86
87 /**
88 * Specifies that a parameter is deprecated and should be transitioned out of usage.
89 *
90 * @return whether or not the parameter is deprecated
91 **/
92 boolean deprecated() default false;
93
94 /**
95 * When true, allows sending an empty value. If false, the parameter will be considered \"null\" if no value is present. This may create validation errors when the parameter is required.
96 *
97 * @return whether or not the parameter allows empty values
98 **/
99 boolean allowEmptyValue() default false;
100
101 /**
102 * Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form. Ignored if the properties content or array are specified.
103 *
104 * @return the style of the parameter
105 **/
106 ParameterStyle style() default ParameterStyle.DEFAULT;
107
108 /**
109 * 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.
110 *
111 * @return whether or not to expand individual array members
112 **/
113 Explode explode() default Explode.DEFAULT;
114
115 /**
116 * Determines whether the parameter value should allow reserved characters, as defined by RFC3986. This property only applies to parameters with an in value of query. The default value is false. Ignored if the properties content or array are specified.
117 *
118 * @return whether or not the parameter allows reserved characters
119 **/
120 boolean allowReserved() default false;
121
122 /**
123 * The schema defining the type used for the parameter. Ignored if the properties content or array are specified.
124 *
125 * @return the schema of the parameter
126 **/
127 Schema schema() default @Schema();
128
129 /**
130 * The schema of the array that defines this parameter. Ignored if the property content is specified.
131 *
132 * @return the schema of the array
133 */
134 ArraySchema array() default @ArraySchema();
135
136 /**
137 * The representation of this parameter, for different media types.
138 *
139 * @return the content of the parameter
140 **/
141 Content[] content() default {};
142
143 /**
144 * Allows this parameter to be marked as hidden
145 *
146 * @return whether or not this parameter is hidden
147 */
148 boolean hidden() default false;
149
150 /**
151 * An array of examples of the schema used to show the use of the associated schema.
152 *
153 * @return array of examples of the parameter
154 **/
155 ExampleObject[] examples() default {};
156
157 /**
158 * 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.
159 *
160 * @return an example of the parameter
161 **/
162 String example() default "";
163
164 /**
165 * The list of optional extensions
166 *
167 * @return an optional array of extensions
168 */
169 Extension[] extensions() default {};
170
171 /**
172 * A reference to a parameter defined in components parameter.
173 *
174 * @since 2.0.3
175 * @return the reference
176 **/
177 String ref() default "";
178 }
179