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