001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019import java.util.*; 020 021import org.apache.juneau.collections.*; 022import org.apache.juneau.http.annotation.*; 023import org.apache.juneau.httppart.*; 024import org.apache.juneau.oapi.*; 025 026/** 027 * Swagger schema annotation. 028 * 029 * <p> 030 * The Schema Object allows the definition of input and output data types. 031 * These types can be objects, but also primitives and arrays. 032 * This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. 033 * On top of this subset, there are extensions provided by this specification to allow for more complete documentation. 034 * 035 * <p> 036 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@Rest</ja>-annotated classes. 037 * <br>Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiSerializer} and parsed through {@link OpenApiParser}. 038 * 039 * <h5 class='section'>Examples:</h5> 040 * <p class='bjava'> 041 * <jc>// A response object thats a hex-encoded string</jc> 042 * <ja>@Response</ja>( 043 * schema=<ja>@Schema</ja>( 044 * type=<js>"string"</js>, 045 * format=<js>"binary"</js> 046 * ) 047 * ) 048 * </p> 049 * <p class='bjava'> 050 * <jc>// A request body consisting of an array of arrays, the internal 051 * // array being of type integer, numbers must be between 0 and 63 (inclusive)</jc> 052 * <ja>@Content</ja>( 053 * schema=<ja>@Schema</ja>( 054 * items=<ja>@Items</ja>( 055 * type=<js>"array"</js>, 056 * items=<ja>@SubItems</ja>( 057 * type=<js>"integer"</js>, 058 * minimum=<js>"0"</js>, 059 * maximum=<js>"63"</js> 060 * ) 061 * ) 062 * ) 063 * ) 064 * </p> 065 * 066 * <h5 class='section'>See Also:</h5><ul> 067 * <li class='link'><a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> 068 * <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a> 069 070 * </ul> 071 */ 072@Documented 073@Target({PARAMETER,METHOD,TYPE,FIELD}) 074@Retention(RUNTIME) 075@Repeatable(SchemaAnnotation.Array.class) 076@ContextApply(SchemaAnnotation.Apply.class) 077public @interface Schema { 078 079 /** 080 * <mk>default</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 081 * 082 * <p> 083 * Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. 084 * <br>(Note: "default" has no meaning for required parameters.) 085 * 086 * <p> 087 * Additionally, this value is used to create instances of POJOs that are then serialized as language-specific examples in the generated Swagger documentation 088 * if the examples are not defined in some other way. 089 * 090 * <p> 091 * The format of this value is a string. 092 * <br>Multiple lines are concatenated with newlines. 093 * 094 * <h5 class='section'>Examples:</h5> 095 * <p class='bjava'> 096 * <jk>public</jk> Order placeOrder( 097 * <ja>@Header</ja>(<js>"X-PetId"</js>) 098 * <ja>@Schema</ja>(_default=<js>"100"</js>) 099 * <jk>long</jk> <jv>petId</jv>, 100 * 101 * <ja>@Header</ja>(<js>"X-AdditionalInfo"</js>) 102 * <ja>@Schema</ja>(format=<js>"uon"</js>, _default=<js>"(rushOrder=false)"</js>) 103 * AdditionalInfo <jv>additionalInfo</jv>, 104 * 105 * <ja>@Header</ja>(<js>"X-Flags"</js>) 106 * <ja>@Schema</ja>(collectionFormat=<js>"uon"</js>, _default=<js>"@(new-customer)"</js>) 107 * String[] <jv>flags</jv> 108 * ) {...} 109 * </p> 110 * 111 * <h5 class='section'>Used for:</h5> 112 * <ul class='spaced-list'> 113 * <li> 114 * Server-side schema-based parsing. 115 * <li> 116 * Server-side generated Swagger documentation. 117 * <li> 118 * Client-side schema-based serializing. 119 * </ul> 120 * 121 * @return The annotation value. 122 */ 123 String[] _default() default {}; 124 125 /** 126 * <mk>enum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 127 * 128 * <p> 129 * If specified, the input validates successfully if it is equal to one of the elements in this array. 130 * 131 * <p> 132 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 133 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 134 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 135 * 136 * <p> 137 * The format is either individual values or a comma-delimited list. 138 * <br>Multiple lines are concatenated with newlines. 139 * 140 * <h5 class='section'>Examples:</h5> 141 * <p class='bjava'> 142 * <jc>// Comma-delimited list</jc> 143 * <jk>public</jk> Collection<Pet> findPetsByStatus( 144 * <ja>@Header</ja>(<js>"X-Status"</js>) 145 * <ja>@Schema</ja>(_enum=<js>"AVAILABLE,PENDING,SOLD"</js>) 146 * PetStatus <jv>status</jv> 147 * ) {...} 148 * </p> 149 * 150 * <h5 class='section'>Used for:</h5> 151 * <ul class='spaced-list'> 152 * <li> 153 * Server-side schema-based parsing validation. 154 * <li> 155 * Server-side generated Swagger documentation. 156 * <li> 157 * Client-side schema-based serializing validation. 158 * </ul> 159 * 160 * @return The annotation value. 161 */ 162 String[] _enum() default {}; 163 164 /** 165 * <mk>$ref</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 166 * 167 * <p> 168 * A JSON reference to the schema definition. 169 * 170 * <h5 class='section'>Notes:</h5><ul> 171 * <li class='note'> 172 * The format is a <a href='https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03'>JSON Reference</a>. 173 * </ul> 174 * 175 * @return The annotation value. 176 */ 177 String $ref() default ""; 178 179 /** 180 * <mk>additionalProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 181 * 182 * <h5 class='section'>Notes:</h5><ul> 183 * <li class='note'> 184 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 185 * <br>Multiple lines are concatenated with newlines. 186 * </ul> 187 * 188 * @return The annotation value. 189 */ 190 String[] additionalProperties() default {}; 191 192 /** 193 * <mk>allOf</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 194 * 195 * <h5 class='section'>Notes:</h5><ul> 196 * <li class='note'> 197 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 198 * <br>Multiple lines are concatenated with newlines. 199 * </ul> 200 * 201 * @return The annotation value. 202 */ 203 String[] allOf() default {}; 204 205 /** 206 * Synonym for {@link #allowEmptyValue()}. 207 * 208 * @return The annotation value. 209 */ 210 boolean aev() default false; 211 212 /** 213 * <mk>allowEmptyValue</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>. 214 * 215 * <p> 216 * Sets the ability to pass empty-valued heaver values. 217 * 218 * <h5 class='section'>Used for:</h5> 219 * <ul class='spaced-list'> 220 * <li> 221 * Server-side schema-based parsing validation. 222 * <li> 223 * Server-side generated Swagger documentation. 224 * <li> 225 * Client-side schema-based serializing validation. 226 * </ul> 227 * 228 * <p> 229 * <b>Note:</b> This is technically only valid for either query or formData parameters, but support is provided anyway for backwards compatability. 230 * 231 * @return The annotation value. 232 */ 233 boolean allowEmptyValue() default false; 234 235 /** 236 * Synonym for {@link #collectionFormat()}. 237 * 238 * @return The annotation value. 239 */ 240 String cf() default ""; 241 242 /** 243 * <mk>collectionFormat</mk> field. 244 * 245 * <p> 246 * Note that this field isn't part of the Swagger 2.0 specification, but the specification does not specify how 247 * items are supposed to be represented. 248 * 249 * <p> 250 * Determines the format of the array if <c>type</c> <js>"array"</js> is used. 251 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 252 * 253 * <p> 254 * Static strings are defined in {@link CollectionFormatType}. 255 * 256 * <p> 257 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 258 * 259 * <h5 class='section'>Used for:</h5> 260 * <ul class='spaced-list'> 261 * <li> 262 * Server-side schema-based parsing. 263 * <li> 264 * Server-side generated Swagger documentation. 265 * <li> 266 * Client-side schema-based serializing. 267 * </ul> 268 * 269 * <p> 270 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 271 * 272 * <ul class='values'> 273 * <li><js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>). 274 * <li><js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>). 275 * <li><js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>). 276 * <li><js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>). 277 * <li><js>"multi"</js> - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&foo=baz"</js>). 278 * <li><js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>). 279 * </ul> 280 * 281 * @return The annotation value. 282 */ 283 String collectionFormat() default ""; 284 285 /** 286 * Synonym for {@link #description()}. 287 * 288 * @return The annotation value. 289 */ 290 String[] d() default {}; 291 292 /** 293 * <mk>description</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 294 * 295 * <p> 296 * A brief description of the body. This could contain examples of use. 297 * 298 * <h5 class='section'>Examples:</h5> 299 * <p class='bjava'> 300 * <jc>// Used on parameter</jc> 301 * <ja>@RestPost</ja> 302 * <jk>public void</jk> addPet( 303 * <ja>@Content</ja> <ja>@Schema</ja>(description=<js>"Pet object to add to the store"</js>) Pet <jv>input</jv> 304 * ) {...} 305 * </p> 306 * <p class='bjava'> 307 * <jc>// Used on class</jc> 308 * <ja>@RestPost</ja> 309 * <jk>public void</jk> addPet(Pet <jv>input</jv>) {...} 310 * 311 * <ja>@Content</ja> <ja>@Schema</ja>(description=<js>"Pet object to add to the store"</js>) 312 * <jk>public class</jk> Pet {...} 313 * </p> 314 * 315 * <h5 class='section'>Notes:</h5><ul> 316 * <li class='note'> 317 * The format is plain text. 318 * <br>Multiple lines are concatenated with newlines. 319 * <li class='note'> 320 * Supports <a class="doclink" href="../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>) for the swagger generator. 321 * </ul> 322 * 323 * @return The annotation value. 324 */ 325 String[] description() default {}; 326 327 /** 328 * Synonym for {@link #_default()}. 329 * 330 * @return The annotation value. 331 */ 332 String[] df() default {}; 333 334 /** 335 * <mk>discriminator</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 336 * 337 * <h5 class='section'>Notes:</h5><ul> 338 * <li class='note'> 339 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 340 * <br>Multiple lines are concatenated with newlines. 341 * </ul> 342 * 343 * @return The annotation value. 344 */ 345 String discriminator() default ""; 346 347 /** 348 * Synonym for {@link #_enum()}. 349 * 350 * @return The annotation value. 351 */ 352 String[] e() default {}; 353 354 /** 355 * Synonym for {@link #exclusiveMaximum()}. 356 * 357 * @return The annotation value. 358 */ 359 boolean emax() default false; 360 361 /** 362 * Synonym for {@link #exclusiveMinimum()}. 363 * 364 * @return The annotation value. 365 */ 366 boolean emin() default false; 367 368 /** 369 * <mk>exclusiveMaximum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 370 * 371 * <p> 372 * Defines whether the maximum is matched exclusively. 373 * 374 * <p> 375 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 376 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 377 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 378 * 379 * <p> 380 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 381 * <br>If <jk>true</jk>, must be accompanied with <c>maximum</c>. 382 * 383 * <h5 class='section'>Used for:</h5> 384 * <ul class='spaced-list'> 385 * <li> 386 * Server-side schema-based parsing validation. 387 * <li> 388 * Server-side generated Swagger documentation. 389 * <li> 390 * Client-side schema-based serializing validation. 391 * </ul> 392 * 393 * @return The annotation value. 394 */ 395 boolean exclusiveMaximum() default false; 396 397 /** 398 * <mk>exclusiveMinimum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 399 * 400 * <p> 401 * Defines whether the minimum is matched exclusively. 402 * 403 * <p> 404 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 405 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 406 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 407 * 408 * <p> 409 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 410 * <br>If <jk>true</jk>, must be accompanied with <c>minimum</c>. 411 * 412 * <h5 class='section'>Used for:</h5> 413 * <ul class='spaced-list'> 414 * <li> 415 * Server-side schema-based parsing validation. 416 * <li> 417 * Server-side generated Swagger documentation. 418 * <li> 419 * Client-side schema-based serializing validation. 420 * </ul> 421 * 422 * @return The annotation value. 423 */ 424 boolean exclusiveMinimum() default false; 425 426 /** 427 * <mk>externalDocs</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 428 * 429 * <h5 class='section'>Notes:</h5><ul> 430 * <li class='note'> 431 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 432 * <br>Multiple lines are concatenated with newlines. 433 * </ul> 434 * 435 * @return The annotation value. 436 */ 437 ExternalDocs externalDocs() default @ExternalDocs; 438 439 /** 440 * Synonym for {@link #format()}. 441 * 442 * @return The annotation value. 443 */ 444 String f() default ""; 445 446 /** 447 * <mk>format</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 448 * 449 * <p> 450 * The extending format for the previously mentioned <a class="doclink" href="https://swagger.io/specification/v2#parameterType">parameter type</a>. 451 * 452 * <p> 453 * Static strings are defined in {@link FormatType}. 454 * 455 * <h5 class='section'>Examples:</h5> 456 * <p class='bjava'> 457 * <jc>// Used on parameter</jc> 458 * <ja>@RestPut</ja> 459 * <jk>public void</jk> setAge( 460 * <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"integer"</js>, format=<js>"int32"</js>) String <jv>input</jv> 461 * ) {...} 462 * </p> 463 * 464 * <h5 class='section'>Used for:</h5> 465 * <ul class='spaced-list'> 466 * <li> 467 * Server-side schema-based parsing. 468 * <li> 469 * Server-side generated Swagger documentation. 470 * <li> 471 * Client-side schema-based serializing. 472 * </ul> 473 * 474 * <ul class='values'> 475 * <li> 476 * <js>"int32"</js> - Signed 32 bits. 477 * <br>Only valid with type <js>"integer"</js>. 478 * <li> 479 * <js>"int64"</js> - Signed 64 bits. 480 * <br>Only valid with type <js>"integer"</js>. 481 * <li> 482 * <js>"float"</js> - 32-bit floating point number. 483 * <br>Only valid with type <js>"number"</js>. 484 * <li> 485 * <js>"double"</js> - 64-bit floating point number. 486 * <br>Only valid with type <js>"number"</js>. 487 * <li> 488 * <js>"byte"</js> - BASE-64 encoded characters. 489 * <br>Only valid with type <js>"string"</js>. 490 * <br>Parameters of type POJO convertible from string are converted after the string has been decoded. 491 * <li> 492 * <js>"binary"</js> - Hexadecimal encoded octets (e.g. <js>"00FF"</js>). 493 * <br>Only valid with type <js>"string"</js>. 494 * <br>Parameters of type POJO convertible from string are converted after the string has been decoded. 495 * <li> 496 * <js>"date"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>. 497 * <br>Only valid with type <js>"string"</js>. 498 * <li> 499 * <js>"date-time"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>. 500 * <br>Only valid with type <js>"string"</js>. 501 * <li> 502 * <js>"password"</js> - Used to hint UIs the input needs to be obscured. 503 * <br>This format does not affect the serialization or parsing of the parameter. 504 * <li> 505 * <js>"uon"</js> - UON notation (e.g. <js>"(foo=bar,baz=@(qux,123))"</js>). 506 * <br>Only valid with type <js>"object"</js>. 507 * <br>If not specified, then the input is interpreted as plain-text and is converted to a POJO directly. 508 * </ul> 509 * 510 * <h5 class='section'>Notes:</h5><ul> 511 * <li class='note'> 512 * The format is plain text. 513 * </ul> 514 * 515 * <h5 class='section'>See Also:</h5><ul> 516 * <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a> 517 * </ul> 518 * 519 * @return The annotation value. 520 */ 521 String format() default ""; 522 523 /** 524 * Specifies that schema information for this part should not be shown in the generated Swagger documentation. 525 * 526 * @return The annotation value. 527 */ 528 boolean ignore() default false; 529 530 /** 531 * <mk>items</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 532 * 533 * <p> 534 * Describes the type of items in the array. 535 * 536 * <p> 537 * Required if <c>type</c> is <js>"array"</js>. 538 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 539 * 540 * <h5 class='section'>Used for:</h5> 541 * <ul class='spaced-list'> 542 * <li> 543 * Server-side schema-based parsing and parsing validation. 544 * <li> 545 * Server-side generated Swagger documentation. 546 * <li> 547 * Client-side schema-based serializing and serializing validation. 548 * </ul> 549 * 550 * @return The annotation value. 551 */ 552 Items items() default @Items; 553 554 /** 555 * Synonym for {@link #maximum()}. 556 * 557 * @return The annotation value. 558 */ 559 String max() default ""; 560 561 /** 562 * Synonym for {@link #maxItems()}. 563 * 564 * @return The annotation value. 565 */ 566 long maxi() default -1; 567 568 /** 569 * <mk>maximum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 570 * 571 * <p> 572 * Defines the maximum value for a parameter of numeric types. 573 * <br>The value must be a valid JSON number. 574 * 575 * <p> 576 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 577 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 578 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 579 * 580 * <p> 581 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 582 * 583 * <h5 class='section'>Used for:</h5> 584 * <ul class='spaced-list'> 585 * <li> 586 * Server-side schema-based parsing validation. 587 * <li> 588 * Server-side generated Swagger documentation. 589 * <li> 590 * Client-side schema-based serializing validation. 591 * </ul> 592 * 593 * @return The annotation value. 594 */ 595 String maximum() default ""; 596 597 /** 598 * <mk>maxItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 599 * 600 * <p> 601 * An array or collection is valid if its size is less than, or equal to, the value of this keyword. 602 * 603 * <p> 604 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 605 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 606 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 607 * 608 * <p> 609 * Only allowed for the following types: <js>"array"</js>. 610 * 611 * <h5 class='section'>Used for:</h5> 612 * <ul class='spaced-list'> 613 * <li> 614 * Server-side schema-based parsing validation. 615 * <li> 616 * Server-side generated Swagger documentation. 617 * <li> 618 * Client-side schema-based serializing validation. 619 * </ul> 620 * 621 * @return The annotation value. 622 */ 623 long maxItems() default -1; 624 625 /** 626 * Synonym for {@link #maxLength()}. 627 * 628 * @return The annotation value. 629 */ 630 long maxl() default -1; 631 632 /** 633 * <mk>maxLength</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 634 * 635 * <p> 636 * A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword. 637 * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>. 638 * <br>The value <c>-1</c> is always ignored. 639 * 640 * <p> 641 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 642 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 643 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 644 * 645 * <p> 646 * Only allowed for the following types: <js>"string"</js>. 647 * 648 * <h5 class='section'>Used for:</h5> 649 * <ul class='spaced-list'> 650 * <li> 651 * Server-side schema-based parsing validation. 652 * <li> 653 * Server-side generated Swagger documentation. 654 * <li> 655 * Client-side schema-based serializing validation. 656 * </ul> 657 * 658 * @return The annotation value. 659 */ 660 long maxLength() default -1; 661 662 /** 663 * Synonym for {@link #maxProperties()}. 664 * 665 * @return The annotation value. 666 */ 667 long maxp() default -1; 668 669 /** 670 * <mk>maxProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 671 * 672 * <h5 class='section'>Notes:</h5><ul> 673 * <li class='note'> 674 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 675 * <br>Multiple lines are concatenated with newlines. 676 * </ul> 677 * 678 * @return The annotation value. 679 */ 680 long maxProperties() default -1; 681 682 /** 683 * Synonym for {@link #minimum()}. 684 * 685 * @return The annotation value. 686 */ 687 String min() default ""; 688 689 /** 690 * Synonym for {@link #minItems()}. 691 * 692 * @return The annotation value. 693 */ 694 long mini() default -1; 695 696 /** 697 * <mk>minimum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 698 * 699 * <p> 700 * Defines the minimum value for a parameter of numeric types. 701 * <br>The value must be a valid JSON number. 702 * 703 * <p> 704 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 705 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 706 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 707 * 708 * <p> 709 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 710 * 711 * <h5 class='section'>Used for:</h5> 712 * <ul class='spaced-list'> 713 * <li> 714 * Server-side schema-based parsing validation. 715 * <li> 716 * Server-side generated Swagger documentation. 717 * <li> 718 * Client-side schema-based serializing validation. 719 * </ul> 720 * 721 * @return The annotation value. 722 */ 723 String minimum() default ""; 724 725 /** 726 * <mk>minItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 727 * 728 * <p> 729 * An array or collection is valid if its size is greater than, or equal to, the value of this keyword. 730 * 731 * <p> 732 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 733 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 734 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 735 * 736 * <p> 737 * Only allowed for the following types: <js>"array"</js>. 738 * 739 * <h5 class='section'>Used for:</h5> 740 * <ul class='spaced-list'> 741 * <li> 742 * Server-side schema-based parsing validation. 743 * <li> 744 * Server-side generated Swagger documentation. 745 * <li> 746 * Client-side schema-based serializing validation. 747 * </ul> 748 * 749 * @return The annotation value. 750 */ 751 long minItems() default -1; 752 753 /** 754 * Synonym for {@link #minLength()}. 755 * 756 * @return The annotation value. 757 */ 758 long minl() default -1; 759 760 /** 761 * <mk>minLength</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 762 * 763 * <p> 764 * A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword. 765 * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>. 766 * <br>The value <c>-1</c> is always ignored. 767 * 768 * <p> 769 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 770 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 771 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 772 * 773 * <p> 774 * Only allowed for the following types: <js>"string"</js>. 775 * 776 * <h5 class='section'>Used for:</h5> 777 * <ul class='spaced-list'> 778 * <li> 779 * Server-side schema-based parsing validation. 780 * <li> 781 * Server-side generated Swagger documentation. 782 * <li> 783 * Client-side schema-based serializing validation. 784 * </ul> 785 * 786 * @return The annotation value. 787 */ 788 long minLength() default -1; 789 790 /** 791 * Synonym for {@link #minProperties()}. 792 * 793 * @return The annotation value. 794 */ 795 long minp() default -1; 796 797 /** 798 * <mk>minProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 799 * 800 * <h5 class='section'>Notes:</h5><ul> 801 * <li class='note'> 802 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 803 * <br>Multiple lines are concatenated with newlines. 804 * </ul> 805 * 806 * @return The annotation value. 807 */ 808 long minProperties() default -1; 809 810 /** 811 * Synonym for {@link #multipleOf()}. 812 * 813 * @return The annotation value. 814 */ 815 String mo() default ""; 816 817 /** 818 * <mk>multipleOf</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 819 * 820 * <p> 821 * A numeric instance is valid if the result of the division of the instance by this keyword's value is an integer. 822 * <br>The value must be a valid JSON number. 823 * 824 * <p> 825 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 826 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 827 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 828 * 829 * <p> 830 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 831 * 832 * <h5 class='section'>Used for:</h5> 833 * <ul class='spaced-list'> 834 * <li> 835 * Server-side schema-based parsing validation. 836 * <li> 837 * Server-side generated Swagger documentation. 838 * <li> 839 * Client-side schema-based serializing validation. 840 * </ul> 841 * 842 * @return The annotation value. 843 */ 844 String multipleOf() default ""; 845 846 /** 847 * Dynamically apply this annotation to the specified classes/methods/fields. 848 * 849 * <p> 850 * Used in conjunction with {@link org.apache.juneau.BeanContext.Builder#applyAnnotations(Class...)} to dynamically apply an annotation to an existing class/method/field. 851 * It is ignored when the annotation is applied directly to classes/methods/fields. 852 * 853 * <h5 class='section'>Valid patterns:</h5> 854 * <ul class='spaced-list'> 855 * <li>Classes: 856 * <ul> 857 * <li>Fully qualified: 858 * <ul> 859 * <li><js>"com.foo.MyClass"</js> 860 * </ul> 861 * <li>Fully qualified inner class: 862 * <ul> 863 * <li><js>"com.foo.MyClass$Inner1$Inner2"</js> 864 * </ul> 865 * <li>Simple: 866 * <ul> 867 * <li><js>"MyClass"</js> 868 * </ul> 869 * <li>Simple inner: 870 * <ul> 871 * <li><js>"MyClass$Inner1$Inner2"</js> 872 * <li><js>"Inner1$Inner2"</js> 873 * <li><js>"Inner2"</js> 874 * </ul> 875 * </ul> 876 * <li>Methods: 877 * <ul> 878 * <li>Fully qualified with args: 879 * <ul> 880 * <li><js>"com.foo.MyClass.myMethod(String,int)"</js> 881 * <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js> 882 * <li><js>"com.foo.MyClass.myMethod()"</js> 883 * </ul> 884 * <li>Fully qualified: 885 * <ul> 886 * <li><js>"com.foo.MyClass.myMethod"</js> 887 * </ul> 888 * <li>Simple with args: 889 * <ul> 890 * <li><js>"MyClass.myMethod(String,int)"</js> 891 * <li><js>"MyClass.myMethod(java.lang.String,int)"</js> 892 * <li><js>"MyClass.myMethod()"</js> 893 * </ul> 894 * <li>Simple: 895 * <ul> 896 * <li><js>"MyClass.myMethod"</js> 897 * </ul> 898 * <li>Simple inner class: 899 * <ul> 900 * <li><js>"MyClass$Inner1$Inner2.myMethod"</js> 901 * <li><js>"Inner1$Inner2.myMethod"</js> 902 * <li><js>"Inner2.myMethod"</js> 903 * </ul> 904 * </ul> 905 * <li>Fields: 906 * <ul> 907 * <li>Fully qualified: 908 * <ul> 909 * <li><js>"com.foo.MyClass.myField"</js> 910 * </ul> 911 * <li>Simple: 912 * <ul> 913 * <li><js>"MyClass.myField"</js> 914 * </ul> 915 * <li>Simple inner class: 916 * <ul> 917 * <li><js>"MyClass$Inner1$Inner2.myField"</js> 918 * <li><js>"Inner1$Inner2.myField"</js> 919 * <li><js>"Inner2.myField"</js> 920 * </ul> 921 * </ul> 922 * <li>A comma-delimited list of anything on this list. 923 * </ul> 924 * 925 * <h5 class='section'>See Also:</h5><ul> 926 * <li class='link'><a class="doclink" href="../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 927 * </ul> 928 * 929 * @return The annotation value. 930 */ 931 String[] on() default {}; 932 933 /** 934 * Dynamically apply this annotation to the specified classes. 935 * 936 * <p> 937 * Identical to {@link #on()} except allows you to specify class objects instead of a strings. 938 * 939 * <h5 class='section'>See Also:</h5><ul> 940 * <li class='link'><a class="doclink" href="../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 941 * </ul> 942 * 943 * @return The annotation value. 944 */ 945 Class<?>[] onClass() default {}; 946 947 /** 948 * Synonym for {@link #pattern()}. 949 * 950 * @return The annotation value. 951 */ 952 String p() default ""; 953 954 /** 955 * <mk>pattern</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 956 * 957 * <p> 958 * A string input is valid if it matches the specified regular expression pattern. 959 * 960 * <p> 961 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 962 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 963 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 964 * 965 * <h5 class='section'>Example:</h5> 966 * <p class='bjava'> 967 * <ja>@RestPut</ja> 968 * <jk>public void</jk> doPut(<ja>@Content</ja> <ja>@Schema</ja>(pattern=<js>"/\\w+\\.\\d+/"</js>) String <jv>input</jv>) {...} 969 * </p> 970 * 971 * <p> 972 * Only allowed for the following types: <js>"string"</js>. 973 * 974 * <h5 class='section'>Used for:</h5> 975 * <ul class='spaced-list'> 976 * <li> 977 * Server-side schema-based parsing validation. 978 * <li> 979 * Server-side generated Swagger documentation. 980 * <li> 981 * Client-side schema-based serializing validation. 982 * </ul> 983 * 984 * @return The annotation value. 985 */ 986 String pattern() default ""; 987 988 /** 989 * <mk>properties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 990 * 991 * <h5 class='section'>Notes:</h5><ul> 992 * <li class='note'> 993 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 994 * <br>Multiple lines are concatenated with newlines. 995 * </ul> 996 * 997 * @return The annotation value. 998 */ 999 String[] properties() default {}; 1000 1001 /** 1002 * Synonym for {@link #required()}. 1003 * 1004 * @return The annotation value. 1005 */ 1006 boolean r() default false; 1007 1008 /** 1009 * <mk>readOnly</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1010 * 1011 * <h5 class='section'>Notes:</h5><ul> 1012 * <li class='note'> 1013 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 1014 * <br>Multiple lines are concatenated with newlines. 1015 * </ul> 1016 * 1017 * @return The annotation value. 1018 */ 1019 boolean readOnly() default false; 1020 1021 /** 1022 * <mk>required</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1023 * 1024 * <p> 1025 * Determines whether the parameter is mandatory. 1026 * 1027 * <p> 1028 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1029 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1030 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1031 * 1032 * <h5 class='section'>Examples:</h5> 1033 * <p class='bjava'> 1034 * <jc>// Used on parameter</jc> 1035 * <ja>@RestPost</ja> 1036 * <jk>public void</jk> addPet( 1037 * <ja>@Content</ja> <ja>@Schema</ja>(required=<jk>true</jk>) Pet <jv>input</jv> 1038 * ) {...} 1039 * </p> 1040 * <p class='bjava'> 1041 * <jc>// Used on class</jc> 1042 * <ja>@RestPost</ja> 1043 * <jk>public void</jk> addPet(Pet <jv>input</jv>) {...} 1044 * 1045 * <ja>@Content</ja>(required=<jk>true</jk>) 1046 * <jk>public class</jk> Pet {...} 1047 * </p> 1048 * 1049 * <h5 class='section'>Used for:</h5> 1050 * <ul class='spaced-list'> 1051 * <li> 1052 * Server-side schema-based parsing validation. 1053 * <li> 1054 * Server-side generated Swagger documentation. 1055 * <li> 1056 * Client-side schema-based serializing validation. 1057 * </ul> 1058 * 1059 * @return The annotation value. 1060 */ 1061 boolean required() default false; 1062 1063 /** 1064 * Synonym for {@link #readOnly()}. 1065 * 1066 * @return The annotation value. 1067 */ 1068 boolean ro() default false; 1069 1070 /** 1071 * Synonym for {@link #skipIfEmpty()}. 1072 * 1073 * @return The annotation value. 1074 */ 1075 boolean sie() default false; 1076 1077 /** 1078 * Skips this value during serialization if it's an empty string or empty collection/array. 1079 * 1080 * <p> 1081 * Note that <jk>null</jk> values are already ignored. 1082 * 1083 * <h5 class='section'>Used for:</h5> 1084 * <ul class='spaced-list'> 1085 * <li> 1086 * Client-side schema-based serializing. 1087 * </ul> 1088 * 1089 * @return The annotation value. 1090 */ 1091 boolean skipIfEmpty() default false; 1092 1093 /** 1094 * Synonym for {@link #type()}. 1095 * 1096 * @return The annotation value. 1097 */ 1098 String t() default ""; 1099 1100 /** 1101 * <mk>title</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1102 * 1103 * <h5 class='section'>Notes:</h5><ul> 1104 * <li class='note'> 1105 * The format is plain text. 1106 * </ul> 1107 * 1108 * @return The annotation value. 1109 */ 1110 String title() default ""; 1111 1112 /** 1113 * <mk>type</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1114 * 1115 * <p> 1116 * The type of the parameter. 1117 * 1118 * <h5 class='section'>Examples:</h5> 1119 * <p class='bjava'> 1120 * <jc>// Used on parameter</jc> 1121 * <ja>@RestPost</ja> 1122 * <jk>public void</jk> addPet( 1123 * <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"object"</js>) Pet <jv>input</jv> 1124 * ) {...} 1125 * </p> 1126 * <p class='bjava'> 1127 * <jc>// Used on class</jc> 1128 * <ja>@RestPost</ja> 1129 * <jk>public void</jk> addPet(Pet <jv>input</jv>) {...} 1130 * 1131 * <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"object"</js>) 1132 * <jk>public class</jk> Pet {...} 1133 * </p> 1134 * 1135 * <h5 class='section'>Used for:</h5> 1136 * <ul class='spaced-list'> 1137 * <li> 1138 * Server-side schema-based parsing. 1139 * <li> 1140 * Server-side generated Swagger documentation. 1141 * <li> 1142 * Client-side schema-based serializing. 1143 * </ul> 1144 * 1145 * <ul class='values spaced-list'> 1146 * <li> 1147 * <js>"string"</js> 1148 * <br>Parameter must be a string or a POJO convertible from a string. 1149 * <li> 1150 * <js>"number"</js> 1151 * <br>Parameter must be a number primitive or number object. 1152 * <br>If parameter is <c>Object</c>, creates either a <c>Float</c> or <c>Double</c> depending on the size of the number. 1153 * <li> 1154 * <js>"integer"</js> 1155 * <br>Parameter must be a integer/long primitive or integer/long object. 1156 * <br>If parameter is <c>Object</c>, creates either a <c>Short</c>, <c>Integer</c>, or <c>Long</c> depending on the size of the number. 1157 * <li> 1158 * <js>"boolean"</js> 1159 * <br>Parameter must be a boolean primitive or object. 1160 * <li> 1161 * <js>"array"</js> 1162 * <br>Parameter must be an array or collection. 1163 * <br>Elements must be strings or POJOs convertible from strings. 1164 * <br>If parameter is <c>Object</c>, creates an {@link JsonList}. 1165 * <li> 1166 * <js>"object"</js> 1167 * <br>Parameter must be a map or bean. 1168 * <br>If parameter is <c>Object</c>, creates an {@link JsonMap}. 1169 * <br>Note that this is an extension of the OpenAPI schema as Juneau allows for arbitrarily-complex POJOs to be serialized as HTTP parts. 1170 * <li> 1171 * <js>"file"</js> 1172 * <br>This type is currently not supported. 1173 * </ul> 1174 * 1175 * <h5 class='section'>Notes:</h5><ul> 1176 * <li class='note'>Static strings are defined in {@link ParameterType}. 1177 * </ul> 1178 * 1179 * <h5 class='section'>See Also:</h5><ul> 1180 * <li class='extlink'><a class="doclink" href="https://swagger.io/specification#dataTypes">Swagger Data Types</a> 1181 * </ul> 1182 * 1183 * @return The annotation value. 1184 */ 1185 String type() default ""; 1186 1187 /** 1188 * Synonym for {@link #uniqueItems()}. 1189 * 1190 * @return The annotation value. 1191 */ 1192 boolean ui() default false; 1193 1194 /** 1195 * <mk>uniqueItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1196 * 1197 * <p> 1198 * If <jk>true</jk> the input validates successfully if all of its elements are unique. 1199 * 1200 * <p> 1201 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1202 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1203 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1204 * 1205 * <p> 1206 * If the parameter type is a subclass of {@link Set}, this validation is skipped (since a set can only contain unique items anyway). 1207 * <br>Otherwise, the collection or array is checked for duplicate items. 1208 * 1209 * <p> 1210 * Only allowed for the following types: <js>"array"</js>. 1211 * 1212 * <h5 class='section'>Used for:</h5> 1213 * <ul class='spaced-list'> 1214 * <li> 1215 * Server-side schema-based parsing validation. 1216 * <li> 1217 * Server-side generated Swagger documentation. 1218 * <li> 1219 * Client-side schema-based serializing validation. 1220 * </ul> 1221 * 1222 * @return The annotation value. 1223 */ 1224 boolean uniqueItems() default false; 1225 1226 /** 1227 * <mk>xml</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1228 * 1229 * <h5 class='section'>Notes:</h5><ul> 1230 * <li class='note'> 1231 * The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object. 1232 * <br>Multiple lines are concatenated with newlines. 1233 * </ul> 1234 * 1235 * @return The annotation value. 1236 */ 1237 String[] xml() default {}; 1238}