1 package io.swagger.v3.oas.annotations.media;
2
3 import io.swagger.v3.oas.annotations.ExternalDocumentation;
4 import io.swagger.v3.oas.annotations.OpenAPI31;
5 import io.swagger.v3.oas.annotations.StringToClassMapItem;
6 import io.swagger.v3.oas.annotations.extensions.Extension;
7
8 import java.lang.annotation.Inherited;
9 import java.lang.annotation.Retention;
10 import java.lang.annotation.RetentionPolicy;
11 import java.lang.annotation.Target;
12
13 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
14 import static java.lang.annotation.ElementType.TYPE;
15 import static java.lang.annotation.ElementType.FIELD;
16 import static java.lang.annotation.ElementType.METHOD;
17 import static java.lang.annotation.ElementType.PARAMETER;
18
19 /**
20 * The annotation may be used to define a Schema for a set of elements of the OpenAPI spec, and/or to define additional
21 * properties for the schema. It is applicable e.g. to parameters, schema classes (aka "models"), properties of such
22 * models, request and response content, header.
23 *
24 * <p>swagger-core resolver and swagger-jaxrs2 reader engine consider this annotation along with JAX-RS annotations,
25 * element type and context as input to resolve the annotated element into an OpenAPI schema definition for such element.</p>
26 * <p>The annotation may be used also to override partly (e.g. the name) or fully (e.g providing a completely different
27 * representation) the schema of an element; for example if a specific class is provided as value of {@link Schema#implementation()},
28 * it will override the element type</p>
29 *
30 * <p>The annotation {@link ArraySchema} shall be used for array elements; {@link ArraySchema} and {@link Schema} cannot
31 * coexist</p>
32 *
33 * @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>
34 * @see <a target="_new" href="https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/versions/3.1.0.md#schemaObject">Schema (OpenAPI specification)</a>
35 * @see ArraySchema
36 **/
37 @Target({FIELD, METHOD, PARAMETER, TYPE, ANNOTATION_TYPE})
38 @Retention(RetentionPolicy.RUNTIME)
39 @Inherited
40 public @interface Schema {
41 /**
42 * 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.
43 *
44 * @return a class that implements this schema
45 **/
46 Class<?> implementation() default Void.class;
47
48 /**
49 * Provides a java class to be used to disallow matching properties.
50 *
51 * @return a class with disallowed properties
52 **/
53 Class<?> not() default Void.class;
54
55 /**
56 * 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.
57 *
58 * @return the list of possible classes for a single match
59 **/
60 Class<?>[] oneOf() default {};
61
62 /**
63 * 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.
64 *
65 * @return the list of possible class matches
66 **/
67 Class<?>[] anyOf() default {};
68
69 /**
70 * 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
71 *
72 * @return the list of classes to match
73 **/
74 Class<?>[] allOf() default {};
75
76 /**
77 * The name of the schema or property.
78 *
79 * @return the name of the schema
80 **/
81 String name() default "";
82
83 /**
84 * A title to explain the purpose of the schema.
85 *
86 * @return the title of the schema
87 **/
88 String title() default "";
89
90 /**
91 * Constrains a value such that when divided by the multipleOf, the remainder must be an integer. Ignored if the value is 0.
92 *
93 * @return the multiplier constraint of the schema
94 **/
95 double multipleOf() default 0;
96
97 /**
98 * Sets the maximum numeric value for a property. Ignored if the value is an empty string.
99 *
100 * @return the maximum value for this schema
101 **/
102 String maximum() default "";
103
104 /**
105 * if true, makes the maximum value exclusive, or a less-than criteria.
106 *
107 * @return the exclusive maximum value for this schema
108 **/
109 boolean exclusiveMaximum() default false;
110
111 /**
112 * Sets the minimum numeric value for a property. Ignored if the value is an empty string or not a number.
113 *
114 * @return the minimum value for this schema
115 **/
116 String minimum() default "";
117
118 /**
119 * If true, makes the minimum value exclusive, or a greater-than criteria.
120 *
121 * @return the exclusive minimum value for this schema
122 **/
123 boolean exclusiveMinimum() default false;
124
125 /**
126 * Sets the maximum length of a string value. Ignored if the value is negative.
127 *
128 * @return the maximum length of this schema
129 **/
130 int maxLength() default Integer.MAX_VALUE;
131
132 /**
133 * Sets the minimum length of a string value. Ignored if the value is negative.
134 *
135 * @return the minimum length of this schema
136 **/
137 int minLength() default 0;
138
139 /**
140 * A pattern that the value must satisfy. Ignored if the value is an empty string.
141 *
142 * @return the pattern of this schema
143 **/
144 String pattern() default "";
145
146 /**
147 * Constrains the number of arbitrary properties when additionalProperties is defined. Ignored if value is 0.
148 *
149 * @return the maximum number of properties for this schema
150 **/
151 int maxProperties() default 0;
152
153 /**
154 * Constrains the number of arbitrary properties when additionalProperties is defined. Ignored if value is 0.
155 *
156 * @return the minimum number of properties for this schema
157 **/
158 int minProperties() default 0;
159
160 /**
161 * Allows multiple properties in an object to be marked as required.
162 *
163 * @return the list of required schema properties
164 **/
165 String[] requiredProperties() default {};
166
167 /**
168 * Mandates that the annotated item is required or not.
169 *
170 * @deprecated since 2.2.5, replaced by {@link #requiredMode()}
171 *
172 * @return whether this schema is required
173 **/
174 @Deprecated
175 boolean required() default false;
176
177 /**
178 * Allows to specify the required mode (RequiredMode.AUTO, REQUIRED, NOT_REQUIRED)
179 *
180 * RequiredMode.AUTO: will let the library decide based on its heuristics.
181 * RequiredMode.REQUIRED: will force the item to be considered as required regardless of heuristics.
182 * RequiredMode.NOT_REQUIRED: will force the item to be considered as not required regardless of heuristics.
183 *
184 * @since 2.2.5
185 * @return the requiredMode for this schema (property)
186 *
187 */
188 RequiredMode requiredMode() default RequiredMode.AUTO;
189
190 /**
191 * A description of the schema.
192 *
193 * @return the schema's description
194 **/
195 String description() default "";
196
197 /**
198 * 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\"
199 *
200 * @return the schema's format
201 **/
202 String format() default "";
203
204 /**
205 * References a schema definition in an external OpenAPI document.
206 *
207 * @return a reference to this schema
208 **/
209 String ref() default "";
210
211 /**
212 * If true, designates a value as possibly null.
213 *
214 * @return whether or not this schema is nullable
215 **/
216 boolean nullable() default false;
217
218 /**
219 * Sets whether the value should only be read during a response but not read to during a request.
220 *
221 * @deprecated As of 2.0.0, replaced by {@link #accessMode()}
222 *
223 * @return whether or not this schema is read only
224 *
225 **/
226 @Deprecated
227 boolean readOnly() default false;
228
229 /**
230 * Sets whether a value should only be written to during a request but not returned during a response.
231 *
232 * @deprecated As of 2.0.0, replaced by {@link #accessMode()}
233 *
234 * @return whether or not this schema is write only
235 **/
236 @Deprecated
237 boolean writeOnly() default false;
238
239 /**
240 * Allows to specify the access mode (AccessMode.READ_ONLY, READ_WRITE)
241 *
242 * AccessMode.READ_ONLY: value will not be written to during a request but may be returned during a response.
243 * AccessMode.WRITE_ONLY: value will only be written to during a request but not returned during a response.
244 * AccessMode.READ_WRITE: value will be written to during a request and returned during a response.
245 *
246 * @return the accessMode for this schema (property)
247 *
248 */
249 AccessMode accessMode() default AccessMode.AUTO;
250
251 /**
252 * 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.
253 *
254 * @return an example of this schema
255 **/
256 String example() default "";
257
258 /**
259 * Additional external documentation for this schema.
260 *
261 * @return additional schema documentation
262 **/
263 ExternalDocumentation externalDocs() default @ExternalDocumentation();
264
265 /**
266 * Specifies that a schema is deprecated and should be transitioned out of usage.
267 *
268 * @return whether or not this schema is deprecated
269 **/
270 boolean deprecated() default false;
271
272 /**
273 * Provides an override for the basic type of the schema. Must be a valid type per the OpenAPI Specification.
274 *
275 * @return the type of this schema
276 **/
277 String type() default "";
278
279 /**
280 * Provides a list of allowable values. This field map to the enum property in the OAS schema.
281 *
282 * @return a list of allowed schema values
283 */
284 String[] allowableValues() default {};
285
286 /**
287 * Provides a default value.
288 *
289 * @return the default value of this schema
290 */
291 String defaultValue() default "";
292
293 /**
294 * Provides a discriminator property value.
295 *
296 * @return the discriminator property
297 */
298 String discriminatorProperty() default "";
299
300 /**
301 * Provides discriminator mapping values.
302 *
303 * @return the discriminator mappings
304 */
305 DiscriminatorMapping[] discriminatorMapping() default {};
306
307 /**
308 * Allows schema to be marked as hidden.
309 *
310 * @return whether or not this schema is hidden
311 */
312 boolean hidden() default false;
313
314 /**
315 * Allows enums to be resolved as a reference to a scheme added to components section.
316 *
317 * @since 2.1.0
318 * @return whether or not this must be resolved as a reference
319 */
320 boolean enumAsRef() default false;
321
322 /**
323 * An array of the sub types inheriting from this model.
324 */
325 Class<?>[] subTypes() default {};
326
327 /**
328 * The list of optional extensions
329 *
330 * @return an optional array of extensions
331 */
332 Extension[] extensions() default {};
333
334 /**
335 * List of optional items positionally defines before normal items.
336 * @return optional array of items
337 */
338 Class<?>[] prefixItems() default {};
339
340 /**
341 * List of schema types
342 *
343 * @since 2.2.12 / OpenAPI 3.1
344 * @return array of types
345 */
346 @OpenAPI31
347 String[] types() default {};
348
349 /**
350 * @since 2.2.12 / OpenAPI 3.1
351 *
352 * OAS 3.1 version of `exclusiveMaximum`, accepting a numeric value
353 *
354 * @return the exclusive maximum value for this schema
355 **/
356 @OpenAPI31
357 int exclusiveMaximumValue() default 0;
358
359 /**
360 * Provides an exclusive minimum for a expressing exclusive range.
361 *
362 * @since 2.2.12 / OpenAPI 3.1
363 * @return an exclusive minimum.
364 */
365 @OpenAPI31
366 int exclusiveMinimumValue() default 0;
367
368 /**
369 * Specifies contains constrictions expressions.
370 * @return contains expression.
371 */
372 @OpenAPI31
373 Class<?> contains() default Void.class;
374
375 /**
376 * Provides the $id related to this schema.
377 *
378 * @since 2.2.12 / OpenAPI 3.1
379 * @return the $id of schema
380 */
381 @OpenAPI31
382 String $id() default "";
383
384 /**
385 * Provides Json Schema dialect where the schema is valid.
386 *
387 * @since 2.2.12 / OpenAPI 3.1
388 * @return json schema dialect
389 */
390 @OpenAPI31
391 String $schema() default "";
392
393 /**
394 * Provides the $anchor related to schema
395 *
396 * @since 2.2.12 / OpenAPI 3.1
397 * @return $anchor schema
398 */
399 @OpenAPI31
400 String $anchor() default "";
401
402 /**
403 * Provides the $vocabulary related to schema
404 *
405 * @since 2.2.14 / OpenAPI 3.1
406 * @return $vocabulary schema
407 */
408 @OpenAPI31
409 String $vocabulary() default "";
410
411 /**
412 * Provides the $dynamicAnchor related to schema
413 *
414 * @since 2.2.14 / OpenAPI 3.1
415 * @return $dynamicAnchor schema
416 */
417 @OpenAPI31
418 String $dynamicAnchor() default "";
419
420 /**
421 * Provides the content encoding related to this schema
422 *
423 * @since 2.2.12 / OpenAPI 3.1
424 * @return content encoding
425 */
426 @OpenAPI31
427 String contentEncoding() default "";
428
429 /**
430 * Provides the content media type related to this schema
431 *
432 * @since 2.2.12 / OpenAPI 3.1
433 * @return content media type
434 */
435 @OpenAPI31
436 String contentMediaType() default "";
437
438 /**
439 * Provides the content schema related to this schema
440 *
441 * @since 2.2.12 / OpenAPI 3.1
442 * @return content schema
443 */
444 @OpenAPI31
445 Class<?> contentSchema() default Void.class;
446
447 /**
448 * Provides property names related to this schema
449 *
450 * @since 2.2.12 / OpenAPI 3.1
451 * @return property names
452 */
453 @OpenAPI31
454 Class<?> propertyNames() default Void.class;
455
456 /**
457 * Provides max contains related to this schema
458 * @return max contains
459 */
460 @OpenAPI31
461 int maxContains() default Integer.MAX_VALUE;
462
463 /**
464 * Provides min contains related to this schema
465 * @return min contains
466 */
467 @OpenAPI31
468 int minContains() default 0;
469
470 /**
471 * Provides a list of additional items
472 * @return additional items
473 */
474 Class<?> additionalItems() default Void.class;
475
476 /**
477 * Provides a list of unevaluated items
478 * @return unevaluated items
479 */
480 Class<?> unevaluatedItems() default Void.class;
481
482 /**
483 * Provides the if sub schema related to this schema
484 *
485 * @since 2.2.12 / OpenAPI 3.1
486 * @return if sub schema
487 */
488 @OpenAPI31
489 Class<?> _if() default Void.class;
490
491 /**
492 * Provides the else sub schema related to this schema
493 *
494 * @since 2.2.12 / OpenAPI 3.1
495 * @return else sub schema
496 */
497 @OpenAPI31
498 Class<?> _else() default Void.class;
499
500 /**
501 * Provides the then sub schema related to this schema
502 *
503 * @since 2.2.12 / OpenAPI 3.1
504 * @return then sub schema
505 */
506 @OpenAPI31
507 Class<?> then() default Void.class;
508
509 /**
510 * Provides $comment related to this schema
511 *
512 * @since 2.2.12 / OpenAPI 3.1
513 * @return $comment related to schema
514 */
515 @OpenAPI31
516 String $comment() default "";
517
518 /**
519 * Provides a list of examples related to this schema
520 * @return list of examples
521 */
522 Class<?>[] exampleClasses() default {};
523
524 /**
525 * Allows to specify the additionalProperties value
526 *
527 * AdditionalPropertiesValue.TRUE: set to TRUE
528 * AdditionalPropertiesValue.FALSE: set to FALSE
529 * AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION: resolve from @Content.additionalPropertiesSchema
530 * or @Schema.additionalPropertiesSchema
531 *
532 * @since 2.2.0
533 * @return the accessMode for this schema (property)
534 *
535 */
536 AdditionalPropertiesValue additionalProperties() default AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION;
537
538 enum AccessMode {
539 AUTO,
540 READ_ONLY,
541 WRITE_ONLY,
542 READ_WRITE;
543 }
544
545 enum AdditionalPropertiesValue {
546 TRUE,
547 FALSE,
548 USE_ADDITIONAL_PROPERTIES_ANNOTATION;
549 }
550
551 enum RequiredMode {
552 AUTO,
553 REQUIRED,
554 NOT_REQUIRED;
555 }
556
557 /**
558 * Allows to specify the dependentRequired value
559 **
560 * @since 2.2.12 / OpenAPI 3.1
561 * @return the list of DependentRequire annotations
562 *
563 */
564 @OpenAPI31
565 DependentRequired[] dependentRequiredMap() default {};
566
567 /**
568 * Allows to specify the dependentSchemas value providing a Class to be resolved into a Schema
569 *
570 * @since 2.2.12 / OpenAPI 3.1
571 * @return the list of dependentSchemas annotations
572 *
573 */
574 @OpenAPI31
575 StringToClassMapItem[] dependentSchemas() default {};
576
577 /**
578 * Provides pattern properties to this schema
579 *
580 * @since 2.2.12 / OpenAPI 3.1
581 * @return pattern properties
582 */
583 @OpenAPI31
584 StringToClassMapItem[] patternProperties() default {};
585
586 /**
587 * Provides properties related to this schema
588 *
589 * @return schema properties
590 */
591 StringToClassMapItem[] properties() default {};
592
593 /**
594 * Provides unevaluated properties to this schema
595 *
596 * @since 2.2.12 / OpenAPI 3.1
597 * @return unevaluated properties
598 */
599 @OpenAPI31
600 Class<?> unevaluatedProperties() default Void.class;
601 Class<?> additionalPropertiesSchema() default Void.class;
602
603 /**
604 * Provides an array of examples 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.
605 *
606 * @return an array of examples of this schema
607 **/
608 @OpenAPI31
609 String[] examples() default {};
610
611 /**
612 * Provides value restricted to this schema.
613 *
614 * @since 2.2.12 / OpenAPI 3.1
615 * @return const value
616 */
617 @OpenAPI31
618 String _const() default "";
619 }
620