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.media;
18
19 import io.swagger.v3.oas.annotations.ExternalDocumentation;
20 import io.swagger.v3.oas.annotations.extensions.Extension;
21
22 import java.lang.annotation.Inherited;
23 import java.lang.annotation.Retention;
24 import java.lang.annotation.RetentionPolicy;
25 import java.lang.annotation.Target;
26 import java.nio.file.AccessMode;
27
28 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
29 import static java.lang.annotation.ElementType.TYPE;
30 import static java.lang.annotation.ElementType.FIELD;
31 import static java.lang.annotation.ElementType.METHOD;
32 import static java.lang.annotation.ElementType.PARAMETER;
33
34 /**
35 * The annotation may be used to define a Schema for a set of elements of the OpenAPI spec, and/or to define additional
36 * properties for the schema. It is applicable e.g. to parameters, schema classes (aka "models"), properties of such
37 * models, request and response content, header.
38 *
39 * <p>swagger-core resolver and swagger-jaxrs2 reader engine consider this annotation along with JAX-RS annotations,
40 * element type and context as input to resolve the annotated element into an OpenAPI schema definition for such element.</p>
41 * <p>The annotation may be used also to override partly (e.g. the name) or fully (e.g providing a completely different
42 * representation) the schema of an element; for example if a specific class is provided as value of {@link Schema#implementation()},
43 * it will override the element type</p>
44 *
45 * <p>The annotation {@link ArraySchema} shall be used for array elements; {@link ArraySchema} and {@link Schema} cannot
46 * coexist</p>
47 *
48 * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#schemaObject">Schema (OpenAPI specification)</a>
49 * @see ArraySchema
50 **/
51 @Target({FIELD, METHOD, PARAMETER, TYPE, ANNOTATION_TYPE})
52 @Retention(RetentionPolicy.RUNTIME)
53 @Inherited
54 public @interface Schema {
55 /**
56 * Provides a java class as implementation for this schema. When provided, additional information in the Schema annotation (except for type information) will augment the java class after introspection.
57 *
58 * @return a class that implements this schema
59 **/
60 Class<?> implementation() default Void.class;
61
62 /**
63 * Provides a java class to be used to disallow matching properties.
64 *
65 * @return a class with disallowed properties
66 **/
67 Class<?> not() default Void.class;
68
69 /**
70 * Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If more than one match the derived schemas, a validation error will occur.
71 *
72 * @return the list of possible classes for a single match
73 **/
74 Class<?>[] oneOf() default {};
75
76 /**
77 * Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If any match, the schema will be considered valid.
78 *
79 * @return the list of possible class matches
80 **/
81 Class<?>[] anyOf() default {};
82
83 /**
84 * Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If all match, the schema will be considered valid
85 *
86 * @return the list of classes to match
87 **/
88 Class<?>[] allOf() default {};
89
90 /**
91 * The name of the schema or property.
92 *
93 * @return the name of the schema
94 **/
95 String name() default "";
96
97 /**
98 * A title to explain the purpose of the schema.
99 *
100 * @return the title of the schema
101 **/
102 String title() default "";
103
104 /**
105 * Constrains a value such that when divided by the multipleOf, the remainder must be an integer. Ignored if the value is 0.
106 *
107 * @return the multiplier constraint of the schema
108 **/
109 double multipleOf() default 0;
110
111 /**
112 * Sets the maximum numeric value for a property. Ignored if the value is an empty string.
113 *
114 * @return the maximum value for this schema
115 **/
116 String maximum() default "";
117
118 /**
119 * if true, makes the maximum value exclusive, or a less-than criteria.
120 *
121 * @return the exclusive maximum value for this schema
122 **/
123 boolean exclusiveMaximum() default false;
124
125 /**
126 * Sets the minimum numeric value for a property. Ignored if the value is an empty string or not a number.
127 *
128 * @return the minimum value for this schema
129 **/
130 String minimum() default "";
131
132 /**
133 * If true, makes the minimum value exclusive, or a greater-than criteria.
134 *
135 * @return the exclusive minimum value for this schema
136 **/
137 boolean exclusiveMinimum() default false;
138
139 /**
140 * Sets the maximum length of a string value. Ignored if the value is negative.
141 *
142 * @return the maximum length of this schema
143 **/
144 int maxLength() default Integer.MAX_VALUE;
145
146 /**
147 * Sets the minimum length of a string value. Ignored if the value is negative.
148 *
149 * @return the minimum length of this schema
150 **/
151 int minLength() default 0;
152
153 /**
154 * A pattern that the value must satisfy. Ignored if the value is an empty string.
155 *
156 * @return the pattern of this schema
157 **/
158 String pattern() default "";
159
160 /**
161 * Constrains the number of arbitrary properties when additionalProperties is defined. Ignored if value is 0.
162 *
163 * @return the maximum number of properties for this schema
164 **/
165 int maxProperties() default 0;
166
167 /**
168 * Constrains the number of arbitrary properties when additionalProperties is defined. Ignored if value is 0.
169 *
170 * @return the minimum number of properties for this schema
171 **/
172 int minProperties() default 0;
173
174 /**
175 * Allows multiple properties in an object to be marked as required.
176 *
177 * @return the list of required schema properties
178 **/
179 String[] requiredProperties() default {};
180
181 /**
182 * Mandates that the annotated item is required or not.
183 *
184 * @return whether or not this schema is required
185 **/
186 boolean required() default false;
187
188 /**
189 * A description of the schema.
190 *
191 * @return the schema's description
192 **/
193 String description() default "";
194
195 /**
196 * Provides an optional override for the format. If a consumer is unaware of the meaning of the format, they shall fall back to using the basic type without format. For example, if \"type: integer, format: int128\" were used to designate a very large integer, most consumers will not understand how to handle it, and fall back to simply \"type: integer\"
197 *
198 * @return the schema's format
199 **/
200 String format() default "";
201
202 /**
203 * References a schema definition in an external OpenAPI document.
204 *
205 * @return a reference to this schema
206 **/
207 String ref() default "";
208
209 /**
210 * If true, designates a value as possibly null.
211 *
212 * @return whether or not this schema is nullable
213 **/
214 boolean nullable() default false;
215
216 /**
217 * Sets whether the value should only be read during a response but not read to during a request.
218 *
219 * @deprecated As of 2.0.0, replaced by {@link #accessMode()}
220 *
221 * @return whether or not this schema is read only
222 *
223 **/
224 @Deprecated
225 boolean readOnly() default false;
226
227 /**
228 * Sets whether a value should only be written to during a request but not returned during a response.
229 *
230 * @deprecated As of 2.0.0, replaced by {@link #accessMode()}
231 *
232 * @return whether or not this schema is write only
233 **/
234 @Deprecated
235 boolean writeOnly() default false;
236
237 /**
238 * Allows to specify the access mode (AccessMode.READ_ONLY, READ_WRITE)
239 *
240 * AccessMode.READ_ONLY: value will only be written to during a request but not returned during a response.
241 * AccessMode.WRITE_ONLY: value will only be written to during a request but not returned during a response.
242 * AccessMode.READ_WRITE: value will be written to during a request and returned during a response.
243 *
244 * @return the accessMode for this schema (property)
245 *
246 */
247 AccessMode accessMode() default AccessMode.AUTO;
248
249 /**
250 * 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.
251 *
252 * @return an example of this schema
253 **/
254 String example() default "";
255
256 /**
257 * Additional external documentation for this schema.
258 *
259 * @return additional schema documentation
260 **/
261 ExternalDocumentation externalDocs() default @ExternalDocumentation();
262
263 /**
264 * Specifies that a schema is deprecated and should be transitioned out of usage.
265 *
266 * @return whether or not this schema is deprecated
267 **/
268 boolean deprecated() default false;
269
270 /**
271 * Provides an override for the basic type of the schema. Must be a valid type per the OpenAPI Specification.
272 *
273 * @return the type of this schema
274 **/
275 String type() default "";
276
277 /**
278 * Provides a list of allowable values. This field map to the enum property in the OAS schema.
279 *
280 * @return a list of allowed schema values
281 */
282 String[] allowableValues() default {};
283
284 /**
285 * Provides a default value.
286 *
287 * @return the default value of this schema
288 */
289 String defaultValue() default "";
290
291 /**
292 * Provides a discriminator property value.
293 *
294 * @return the discriminator property
295 */
296 String discriminatorProperty() default "";
297
298 /**
299 * Provides discriminator mapping values.
300 *
301 * @return the discriminator mappings
302 */
303 DiscriminatorMapping[] discriminatorMapping() default {};
304
305 /**
306 * Allows schema to be marked as hidden.
307 *
308 * @return whether or not this schema is hidden
309 */
310 boolean hidden() default false;
311
312 /**
313 * Allows enums to be resolved as a reference to a scheme added to components section.
314 *
315 * @since 2.1.0
316 * @return whether or not this must be resolved as a reference
317 */
318 boolean enumAsRef() default false;
319
320 /**
321 * An array of the sub types inheriting from this model.
322 */
323 Class<?>[] subTypes() default {};
324
325 /**
326 * The list of optional extensions
327 *
328 * @return an optional array of extensions
329 */
330 Extension[] extensions() default {};
331
332 enum AccessMode {
333 AUTO,
334 READ_ONLY,
335 WRITE_ONLY,
336 READ_WRITE;
337 }
338 }
339