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.jsonschema.annotation; 014 015import static java.lang.annotation.RetentionPolicy.*; 016 017import java.lang.annotation.*; 018 019import org.apache.juneau.http.annotation.*; 020import org.apache.juneau.oapi.*; 021 022/** 023 * Swagger schema annotation. 024 * 025 * <p> 026 * The Schema Object allows the definition of input and output data types. 027 * These types can be objects, but also primitives and arrays. 028 * This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. 029 * On top of this subset, there are extensions provided by this specification to allow for more complete documentation. 030 * 031 * <p> 032 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@Rest</ja>-annotated classes. 033 * <br>Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiSerializer} and parsed through {@link OpenApiParser}. 034 * 035 * <h5 class='section'>Examples:</h5> 036 * <p class='bcode w800'> 037 * <jc>// A response object thats a hex-encoded string</jc> 038 * <ja>@Response</ja>( 039 * schema=<ja>@Schema</ja>( 040 * type=<js>"string"</js>, 041 * format=<js>"binary"</js> 042 * ) 043 * ) 044 * </p> 045 * <p class='bcode w800'> 046 * <jc>// Free-form</jc> 047 * <ja>@Response</ja>( 048 * schema=<ja>@Schema</ja>({ 049 * <js>"type:'string',"</js>, 050 * <js>"format:'binary'"</js> 051 * }) 052 * ) 053 * </p> 054 * <p class='bcode w800'> 055 * <jc>// A request body consisting of an array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive)</jc> 056</jc> 057 * <ja>@Body</ja>( 058 * schema=<ja>@Schema</ja>( 059 * items=<ja>@Items</ja>( 060 * type=<js>"array"</js>, 061 * items=<ja>@SubItems</ja>( 062 * type=<js>"integer"</js>, 063 * minimum=<js>"0"</js>, 064 * maximum=<js>"63"</js> 065 * ) 066 * ) 067 * ) 068 * ) 069 * </p> 070 * 071 * <ul class='seealso'> 072 * <li class='link'>{@doc RestSwagger} 073 * <li class='extlink'>{@doc ExtSwaggerSchemaObject} 074 * </ul> 075 */ 076@Documented 077@Retention(RUNTIME) 078public @interface Schema { 079 080 /** 081 * <mk>$ref</mk> field of the {@doc ExtSwaggerSchemaObject}. 082 * 083 * <p> 084 * A JSON reference to the schema definition. 085 * 086 * <ul class='notes'> 087 * <li> 088 * The format is a <a href='https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03'>JSON Reference</a>. 089 * <li> 090 * Supports {@doc RestSvlVariables} 091 * (e.g. <js>"$L{my.localized.variable}"</js>). 092 * </ul> 093 */ 094 String $ref() default ""; 095 096 /** 097 * <mk>format</mk> field of the {@doc ExtSwaggerSchemaObject}. 098 * 099 * <h5 class='section'>Examples:</h5> 100 * <p class='bcode w800'> 101 * <jc>// Used on parameter</jc> 102 * <ja>@RestMethod</ja>(name=<jsf>PUT</jsf>) 103 * <jk>public void</jk> setAge( 104 * <ja>@Body</ja>(type=<js>"integer"</js>, format=<js>"int32"</js>) String input 105 * ) {...} 106 * </p> 107 * 108 * <ul class='notes'> 109 * <li> 110 * The format is plain text. 111 * <li> 112 * Supports {@doc RestSvlVariables} 113 * (e.g. <js>"$L{my.localized.variable}"</js>). 114 * </ul> 115 * 116 * <ul class='seealso'> 117 * <li class='extlink'>{@doc ExtSwaggerDataTypeFormats} 118 * </ul> 119 */ 120 String format() default ""; 121 122 /** 123 * Synonym for {@link #format()}. 124 */ 125 String f() default ""; 126 127 /** 128 * <mk>title</mk> field of the {@doc ExtSwaggerSchemaObject}. 129 * 130 * <ul class='notes'> 131 * <li> 132 * The format is plain text. 133 * <li> 134 * Supports {@doc RestSvlVariables} 135 * (e.g. <js>"$L{my.localized.variable}"</js>). 136 * </ul> 137 */ 138 String title() default ""; 139 140 /** 141 * <mk>description</mk> field of the {@doc ExtSwaggerSchemaObject}. 142 * 143 * <p> 144 * A brief description of the body. This could contain examples of use. 145 * 146 * <h5 class='section'>Examples:</h5> 147 * <p class='bcode w800'> 148 * <jc>// Used on parameter</jc> 149 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 150 * <jk>public void</jk> addPet( 151 * <ja>@Body</ja>(description=<js>"Pet object to add to the store"</js>) Pet input 152 * ) {...} 153 * </p> 154 * <p class='bcode w800'> 155 * <jc>// Used on class</jc> 156 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 157 * <jk>public void</jk> addPet(Pet input) {...} 158 * 159 * <ja>@Body</ja>(description=<js>"Pet object to add to the store"</js>) 160 * <jk>public class</jk> Pet {...} 161 * </p> 162 * 163 * <ul class='notes'> 164 * <li> 165 * The format is plain text. 166 * <br>Multiple lines are concatenated with newlines. 167 * <li> 168 * Supports {@doc RestSvlVariables} 169 * (e.g. <js>"$L{my.localized.variable}"</js>). 170 * </ul> 171 */ 172 String[] description() default {}; 173 174 /** 175 * Synonym for {@link #description()}. 176 */ 177 String[] d() default {}; 178 179 /** 180 * <mk>default</mk> field of the {@doc ExtSwaggerSchemaObject}. 181 * 182 * <ul class='notes'> 183 * <li> 184 * The format is any {@doc SimplifiedJson}. 185 * <br>Multiple lines are concatenated with newlines. 186 * <li> 187 * Supports {@doc RestSvlVariables} 188 * (e.g. <js>"$L{my.localized.variable}"</js>). 189 * </ul> 190 */ 191 String[] _default() default {}; 192 193 /** 194 * Synonym for {@link #_default()}. 195 */ 196 String[] df() default {}; 197 198 /** 199 * <mk>multipleOf</mk> field of the {@doc ExtSwaggerSchemaObject}. 200 * 201 * <ul class='notes'> 202 * <li> 203 * The format is numeric. 204 * <li> 205 * Supports {@doc RestSvlVariables} 206 * (e.g. <js>"$L{my.localized.variable}"</js>). 207 * </ul> 208 */ 209 String multipleOf() default ""; 210 211 /** 212 * Synonym for {@link #multipleOf()}. 213 */ 214 String mo() default ""; 215 216 /** 217 * <mk>maximum</mk> field of the {@doc ExtSwaggerSchemaObject}. 218 * 219 * <ul class='notes'> 220 * <li> 221 * The format is numeric. 222 * <li> 223 * Supports {@doc RestSvlVariables} 224 * (e.g. <js>"$L{my.localized.variable}"</js>). 225 * </ul> 226 */ 227 String maximum() default ""; 228 229 /** 230 * Synonym for {@link #maximum()}. 231 */ 232 String max() default ""; 233 234 /** 235 * <mk>exclusiveMaximum</mk> field of the {@doc ExtSwaggerSchemaObject}. 236 * 237 * <ul class='notes'> 238 * <li> 239 * The format is numeric. 240 * <li> 241 * Supports {@doc RestSvlVariables} 242 * (e.g. <js>"$L{my.localized.variable}"</js>). 243 * </ul> 244 */ 245 boolean exclusiveMaximum() default false; 246 247 /** 248 * Synonym for {@link #exclusiveMaximum()}. 249 */ 250 boolean emax() default false; 251 252 /** 253 * <mk>minimum</mk> field of the {@doc ExtSwaggerSchemaObject}. 254 * 255 * <ul class='notes'> 256 * <li> 257 * The format is numeric. 258 * <li> 259 * Supports {@doc RestSvlVariables} 260 * (e.g. <js>"$L{my.localized.variable}"</js>). 261 * </ul> 262 */ 263 String minimum() default ""; 264 265 /** 266 * Synonym for {@link #minimum()}. 267 */ 268 String min() default ""; 269 270 /** 271 * <mk>exclusiveMinimum</mk> field of the {@doc ExtSwaggerSchemaObject}. 272 * 273 * <ul class='notes'> 274 * <li> 275 * The format is numeric. 276 * <li> 277 * Supports {@doc RestSvlVariables} 278 * (e.g. <js>"$L{my.localized.variable}"</js>). 279 * </ul> 280 */ 281 boolean exclusiveMinimum() default false; 282 283 /** 284 * Synonym for {@link #exclusiveMinimum()}. 285 */ 286 boolean emin() default false; 287 288 /** 289 * <mk>maxLength</mk> field of the {@doc ExtSwaggerSchemaObject}. 290 * 291 * <ul class='notes'> 292 * <li> 293 * The format is numeric. 294 * <li> 295 * Supports {@doc RestSvlVariables} 296 * (e.g. <js>"$L{my.localized.variable}"</js>). 297 * </ul> 298 */ 299 long maxLength() default -1; 300 301 /** 302 * Synonym for {@link #maxLength()}. 303 */ 304 long maxl() default -1; 305 306 /** 307 * <mk>minLength</mk> field of the {@doc ExtSwaggerSchemaObject}. 308 * 309 * <ul class='notes'> 310 * <li> 311 * The format is numeric. 312 * <li> 313 * Supports {@doc RestSvlVariables} 314 * (e.g. <js>"$L{my.localized.variable}"</js>). 315 * </ul> 316 */ 317 long minLength() default -1; 318 319 /** 320 * Synonym for {@link #minLength()}. 321 */ 322 long minl() default -1; 323 324 /** 325 * <mk>pattern</mk> field of the {@doc ExtSwaggerSchemaObject}. 326 * 327 * <h5 class='section'>Example:</h5> 328 * <p class='bcode w800'> 329 * <ja>@RestMethod</ja>(name=<jsf>PUT</jsf>) 330 * <jk>public void</jk> doPut(<ja>@Body</ja>(format=<js>"/\\w+\\.\\d+/"</js>) String input) {...} 331 * </p> 332 * 333 * <ul class='notes'> 334 * <li> 335 * The format is plain text. 336 * <li> 337 * This string SHOULD be a valid regular expression. 338 * <li> 339 * Supports {@doc RestSvlVariables} 340 * (e.g. <js>"$L{my.localized.variable}"</js>). 341 * </ul> 342 */ 343 String pattern() default ""; 344 345 /** 346 * Synonym for {@link #pattern()}. 347 */ 348 String p() default ""; 349 350 /** 351 * <mk>maxItems</mk> field of the {@doc ExtSwaggerSchemaObject}. 352 * 353 * <ul class='notes'> 354 * <li> 355 * The format is numeric. 356 * <li> 357 * Supports {@doc RestSvlVariables} 358 * (e.g. <js>"$L{my.localized.variable}"</js>). 359 * </ul> 360 */ 361 long maxItems() default -1; 362 363 /** 364 * Synonym for {@link #maxItems()}. 365 */ 366 long maxi() default -1; 367 368 /** 369 * <mk>minItems</mk> field of the {@doc ExtSwaggerSchemaObject}. 370 * 371 * <ul class='notes'> 372 * <li> 373 * The format is numeric. 374 * <li> 375 * Supports {@doc RestSvlVariables} 376 * (e.g. <js>"$L{my.localized.variable}"</js>). 377 * </ul> 378 */ 379 long minItems() default -1; 380 381 /** 382 * Synonym for {@link #minItems()}. 383 */ 384 long mini() default -1; 385 386 /** 387 * <mk>uniqueItems</mk> field of the {@doc ExtSwaggerSchemaObject}. 388 * 389 * <ul class='notes'> 390 * <li> 391 * The format is boolean. 392 * <li> 393 * Supports {@doc RestSvlVariables} 394 * (e.g. <js>"$L{my.localized.variable}"</js>). 395 * </ul> 396 */ 397 boolean uniqueItems() default false; 398 399 /** 400 * Synonym for {@link #uniqueItems()}. 401 */ 402 boolean ui() default false; 403 404 /** 405 * <mk>maxProperties</mk> field of the {@doc ExtSwaggerSchemaObject}. 406 * 407 * <ul class='notes'> 408 * <li> 409 * The format is a {@doc SimplifiedJson} object. 410 * <br>Multiple lines are concatenated with newlines. 411 * <li> 412 * Supports {@doc RestSvlVariables} 413 * (e.g. <js>"$L{my.localized.variable}"</js>). 414 * </ul> 415 */ 416 long maxProperties() default -1; 417 418 /** 419 * Synonym for {@link #maxProperties()}. 420 */ 421 long maxp() default -1; 422 423 /** 424 * <mk>minProperties</mk> field of the {@doc ExtSwaggerSchemaObject}. 425 * 426 * <ul class='notes'> 427 * <li> 428 * The format is a {@doc SimplifiedJson} object. 429 * <br>Multiple lines are concatenated with newlines. 430 * <li> 431 * Supports {@doc RestSvlVariables} 432 * (e.g. <js>"$L{my.localized.variable}"</js>). 433 * </ul> 434 */ 435 long minProperties() default -1; 436 437 /** 438 * Synonym for {@link #minProperties()}. 439 */ 440 long minp() default -1; 441 442 /** 443 * <mk>required</mk> field of the {@doc ExtSwaggerSchemaObject}. 444 * 445 * <p> 446 * Determines whether this parameter is mandatory. 447 * <br>The property MAY be included and its default value is false. 448 * 449 * <h5 class='section'>Examples:</h5> 450 * <p class='bcode w800'> 451 * <jc>// Used on parameter</jc> 452 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 453 * <jk>public void</jk> addPet( 454 * <ja>@Body</ja>(required=<jk>true</jk>) Pet input 455 * ) {...} 456 * </p> 457 * <p class='bcode w800'> 458 * <jc>// Used on class</jc> 459 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 460 * <jk>public void</jk> addPet(Pet input) {...} 461 * 462 * <ja>@Body</ja>(required=<jk>true</jk>) 463 * <jk>public class</jk> Pet {...} 464 * </p> 465 * 466 * <ul class='notes'> 467 * <li> 468 * The format is boolean. 469 * <li> 470 * Supports {@doc RestSvlVariables} 471 * (e.g. <js>"$L{my.localized.variable}"</js>). 472 * </ul> 473 */ 474 boolean required() default false; 475 476 /** 477 * Synonym for {@link #required()}. 478 */ 479 boolean r() default false; 480 481 /** 482 * <mk>enum</mk> field of the {@doc ExtSwaggerSchemaObject}. 483 * 484 * <ul class='notes'> 485 * <li> 486 * The format is a {@doc SimplifiedJson} array or comma-delimited list. 487 * <br>Multiple lines are concatenated with newlines. 488 * <li> 489 * Supports {@doc RestSvlVariables} 490 * (e.g. <js>"$L{my.localized.variable}"</js>). 491 * </ul> 492 */ 493 String[] _enum() default {}; 494 495 /** 496 * Synonym for {@link #_enum()}. 497 */ 498 String[] e() default {}; 499 500 /** 501 * <mk>type</mk> field of the {@doc ExtSwaggerSchemaObject}. 502 * 503 * <h5 class='section'>Examples:</h5> 504 * <p class='bcode w800'> 505 * <jc>// Used on parameter</jc> 506 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 507 * <jk>public void</jk> addPet( 508 * <ja>@Body</ja>(type=<js>"object"</js>) Pet input 509 * ) {...} 510 * </p> 511 * <p class='bcode w800'> 512 * <jc>// Used on class</jc> 513 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 514 * <jk>public void</jk> addPet(Pet input) {...} 515 * 516 * <ja>@Body</ja>(type=<js>"object"</js>) 517 * <jk>public class</jk> Pet {...} 518 * </p> 519 * 520 * <ul class='notes'> 521 * <li> 522 * The format is plain text. 523 * <li> 524 * The possible values are: 525 * <ul> 526 * <li><js>"object"</js> 527 * <li><js>"string"</js> 528 * <li><js>"number"</js> 529 * <li><js>"integer"</js> 530 * <li><js>"boolean"</js> 531 * <li><js>"array"</js> 532 * <li><js>"file"</js> 533 * </ul> 534 * <li> 535 * Supports {@doc RestSvlVariables} 536 * (e.g. <js>"$L{my.localized.variable}"</js>). 537 * </ul> 538 * 539 * <ul class='seealso'> 540 * <li class='extlink'>{@doc ExtSwaggerDataTypes} 541 * </ul> 542 * 543 */ 544 String type() default ""; 545 546 /** 547 * Synonym for {@link #type()}. 548 */ 549 String t() default ""; 550 551 /** 552 * <mk>items</mk> field of the {@doc ExtSwaggerSchemaObject}. 553 * 554 * <ul class='notes'> 555 * <li> 556 * The format is a {@doc SimplifiedJson} object. 557 * <br>Multiple lines are concatenated with newlines. 558 * <li> 559 * Supports {@doc RestSvlVariables} 560 * (e.g. <js>"$L{my.localized.variable}"</js>). 561 * </ul> 562 */ 563 Items items() default @Items; 564 565 /** 566 * <mk>collectionFormat</mk> field. 567 * 568 * <p> 569 * Note that this field isn't part of the Swagger 2.0 specification, but the specification does not specify how 570 * items are supposed to be represented. 571 * 572 * <p> 573 * Determines the format of the array if <c>type</c> <js>"array"</js> is used. 574 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 575 * 576 * <br>Possible values are: 577 * <ul class='spaced-list'> 578 * <li> 579 * <js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>). 580 * <li> 581 * <js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>). 582 * <li> 583 * <js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>). 584 * <li> 585 * <js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>). 586 * <li> 587 * <js>"multi"</js> - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&foo=baz"</js>). 588 * <li> 589 * <js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>). 590 * </ul> 591 * 592 * <p> 593 * Static strings are defined in {@link CollectionFormatType}. 594 * 595 * <p> 596 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 597 * 598 * <h5 class='section'>Used for:</h5> 599 * <ul class='spaced-list'> 600 * <li> 601 * Server-side schema-based parsing. 602 * <li> 603 * Server-side generated Swagger documentation. 604 * <li> 605 * Client-side schema-based serializing. 606 * </ul> 607 */ 608 String collectionFormat() default ""; 609 610 /** 611 * Synonym for {@link #collectionFormat()}. 612 */ 613 String cf() default ""; 614 615 /** 616 * <mk>allOf</mk> field of the {@doc ExtSwaggerSchemaObject}. 617 * 618 * <ul class='notes'> 619 * <li> 620 * The format is a {@doc SimplifiedJson} object. 621 * <br>Multiple lines are concatenated with newlines. 622 * <li> 623 * Supports {@doc RestSvlVariables} 624 * (e.g. <js>"$L{my.localized.variable}"</js>). 625 * </ul> 626 */ 627 String[] allOf() default {}; 628 629 /** 630 * <mk>properties</mk> field of the {@doc ExtSwaggerSchemaObject}. 631 * 632 * <ul class='notes'> 633 * <li> 634 * The format is a {@doc SimplifiedJson} object. 635 * <br>Multiple lines are concatenated with newlines. 636 * <li> 637 * Supports {@doc RestSvlVariables} 638 * (e.g. <js>"$L{my.localized.variable}"</js>). 639 * </ul> 640 */ 641 String[] properties() default {}; 642 643 /** 644 * <mk>additionalProperties</mk> field of the {@doc ExtSwaggerSchemaObject}. 645 * 646 * <ul class='notes'> 647 * <li> 648 * The format is a {@doc SimplifiedJson} object. 649 * <br>Multiple lines are concatenated with newlines. 650 * <li> 651 * Supports {@doc RestSvlVariables} 652 * (e.g. <js>"$L{my.localized.variable}"</js>). 653 * </ul> 654 */ 655 String[] additionalProperties() default {}; 656 657 /** 658 * <mk>discriminator</mk> field of the {@doc ExtSwaggerSchemaObject}. 659 * 660 * <ul class='notes'> 661 * <li> 662 * The format is a {@doc SimplifiedJson} object. 663 * <br>Multiple lines are concatenated with newlines. 664 * <li> 665 * Supports {@doc RestSvlVariables} 666 * (e.g. <js>"$L{my.localized.variable}"</js>). 667 * </ul> 668 */ 669 String discriminator() default ""; 670 671 /** 672 * <mk>readOnly</mk> field of the {@doc ExtSwaggerSchemaObject}. 673 * 674 * <ul class='notes'> 675 * <li> 676 * The format is a {@doc SimplifiedJson} object. 677 * <br>Multiple lines are concatenated with newlines. 678 * <li> 679 * Supports {@doc RestSvlVariables} 680 * (e.g. <js>"$L{my.localized.variable}"</js>). 681 * </ul> 682 */ 683 boolean readOnly() default false; 684 685 /** 686 * Synonym for {@link #readOnly()}. 687 */ 688 boolean ro() default false; 689 690 /** 691 * <mk>xml</mk> field of the {@doc ExtSwaggerSchemaObject}. 692 * 693 * <ul class='notes'> 694 * <li> 695 * The format is a {@doc SimplifiedJson} object. 696 * <br>Multiple lines are concatenated with newlines. 697 * <li> 698 * Supports {@doc RestSvlVariables} 699 * (e.g. <js>"$L{my.localized.variable}"</js>). 700 * </ul> 701 */ 702 String[] xml() default {}; 703 704 /** 705 * <mk>externalDocs</mk> field of the {@doc ExtSwaggerSchemaObject}. 706 * 707 * <ul class='notes'> 708 * <li> 709 * The format is a {@doc SimplifiedJson} object. 710 * <br>Multiple lines are concatenated with newlines. 711 * <li> 712 * Supports {@doc RestSvlVariables} 713 * (e.g. <js>"$L{my.localized.variable}"</js>). 714 * </ul> 715 */ 716 ExternalDocs externalDocs() default @ExternalDocs; 717 718 /** 719 * <mk>example</mk> field of the {@doc ExtSwaggerSchemaObject}. 720 * 721 * <p> 722 * A free-form property to include an example of an instance for this schema. 723 * 724 * <p> 725 * This attribute defines a JSON representation of the body value that is used by <c>BasicRestInfoProvider</c> to construct 726 * media-type-based examples of the body of the request. 727 * 728 * <ul class='notes'> 729 * <li> 730 * The format is a {@doc SimplifiedJson} object or plain text string. 731 * <br>Multiple lines are concatenated with newlines. 732 * <li> 733 * Supports {@doc RestSvlVariables} 734 * (e.g. <js>"$L{my.localized.variable}"</js>). 735 * </ul> 736 */ 737 String[] example() default {}; 738 739 /** 740 * Synonym for {@link #readOnly()}. 741 */ 742 String[] ex() default {}; 743 744 /** 745 * <mk>x-examples</mk> field of the {@doc ExtSwaggerSchemaObject}. 746 * 747 * <p> 748 * This is a JSON object whose keys are media types and values are string representations of that value. 749 * 750 * <ul class='notes'> 751 * <li> 752 * The format is a {@doc SimplifiedJson} object. 753 * <br>Multiple lines are concatenated with newlines. 754 * <li> 755 * Supports {@doc RestSvlVariables} 756 * (e.g. <js>"$L{my.localized.variable}"</js>). 757 * </ul> 758 */ 759 String[] examples() default {}; 760 761 /** 762 * Synonym for {@link #examples()}. 763 */ 764 String[] exs() default {}; 765 766 /** 767 * Specifies that schema information for this part should not be shown in the generated Swagger documentation. 768 */ 769 boolean ignore() default false; 770 771 /** 772 * Free-form value for the {@doc ExtSwaggerSchemaObject}. 773 * 774 * <p> 775 * This is a JSON object that makes up the swagger information for this field. 776 * 777 * <p> 778 * The following are completely equivalent ways of defining the swagger description of a Schema object: 779 * <p class='bcode w800'> 780 * <jc>// Normal</jc> 781 * <ja>@Schema</ja>( 782 * type=<js>"array"</js>, 783 * items=<ja>@Items</ja>( 784 * $ref=<js>"#/definitions/Pet"</js> 785 * ) 786 * ) 787 * </p> 788 * <p class='bcode w800'> 789 * <jc>// Free-form</jc> 790 * <ja>@Schema</ja>(<js>"type:'array',items:{$ref:'#/definitions/Pet'}"</js>) 791 * </p> 792 * <p class='bcode w800'> 793 * <jc>// Free-form using variables</jc> 794 * <ja>@Schema</ja>(<js>"$L{petArraySwagger}"</js>) 795 * </p> 796 * <p class='bcode w800'> 797 * <mc>// Contents of MyResource.properties</mc> 798 * <mk>petArraySwagger</mk> = <mv>{ type: "array", items: { $ref: "#/definitions/Pet" } }</mv> 799 * </p> 800 * 801 * <p> 802 * The reasons why you may want to use this field include: 803 * <ul> 804 * <li>You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file. 805 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 806 * </ul> 807 * 808 * <ul class='notes'> 809 * <li> 810 * The format is a {@doc SimplifiedJson} object. 811 * <li> 812 * The leading/trailing <c>{ }</c> characters are optional. 813 * <br>The following two example are considered equivalent: 814 * <p class='bcode w800'> 815 * <ja>@Schema</ja>(<js>"{type: 'array'}"</js>) 816 * </p> 817 * <p class='bcode w800'> 818 * <ja>@Schema</ja>(<js>"type: 'array'"</js>) 819 * </p> 820 * <li> 821 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 822 * <li> 823 * Supports {@doc RestSvlVariables} 824 * (e.g. <js>"$L{my.localized.variable}"</js>). 825 * <li> 826 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 827 * </ul> 828 */ 829 String[] value() default {}; 830 831 /** 832 * Dynamically apply this annotation to the specified classes/methods/fields. 833 * 834 * <p> 835 * Used in conjunction with the {@link JsonSchemaConfig#applySchema()}. 836 * It is ignored when the annotation is applied directly to classes/methods/fields. 837 * 838 * <h5 class='section'>Valid patterns:</h5> 839 * <ul class='spaced-list'> 840 * <li>Classes: 841 * <ul> 842 * <li>Fully qualified: 843 * <ul> 844 * <li><js>"com.foo.MyClass"</js> 845 * </ul> 846 * <li>Fully qualified inner class: 847 * <ul> 848 * <li><js>"com.foo.MyClass$Inner1$Inner2"</js> 849 * </ul> 850 * <li>Simple: 851 * <ul> 852 * <li><js>"MyClass"</js> 853 * </ul> 854 * <li>Simple inner: 855 * <ul> 856 * <li><js>"MyClass$Inner1$Inner2"</js> 857 * <li><js>"Inner1$Inner2"</js> 858 * <li><js>"Inner2"</js> 859 * </ul> 860 * </ul> 861 * <li>Methods: 862 * <ul> 863 * <li>Fully qualified with args: 864 * <ul> 865 * <li><js>"com.foo.MyClass.myMethod(String,int)"</js> 866 * <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js> 867 * <li><js>"com.foo.MyClass.myMethod()"</js> 868 * </ul> 869 * <li>Fully qualified: 870 * <ul> 871 * <li><js>"com.foo.MyClass.myMethod"</js> 872 * </ul> 873 * <li>Simple with args: 874 * <ul> 875 * <li><js>"MyClass.myMethod(String,int)"</js> 876 * <li><js>"MyClass.myMethod(java.lang.String,int)"</js> 877 * <li><js>"MyClass.myMethod()"</js> 878 * </ul> 879 * <li>Simple: 880 * <ul> 881 * <li><js>"MyClass.myMethod"</js> 882 * </ul> 883 * <li>Simple inner class: 884 * <ul> 885 * <li><js>"MyClass$Inner1$Inner2.myMethod"</js> 886 * <li><js>"Inner1$Inner2.myMethod"</js> 887 * <li><js>"Inner2.myMethod"</js> 888 * </ul> 889 * </ul> 890 * <li>Fields: 891 * <ul> 892 * <li>Fully qualified: 893 * <ul> 894 * <li><js>"com.foo.MyClass.myField"</js> 895 * </ul> 896 * <li>Simple: 897 * <ul> 898 * <li><js>"MyClass.myField"</js> 899 * </ul> 900 * <li>Simple inner class: 901 * <ul> 902 * <li><js>"MyClass$Inner1$Inner2.myField"</js> 903 * <li><js>"Inner1$Inner2.myField"</js> 904 * <li><js>"Inner2.myField"</js> 905 * </ul> 906 * </ul> 907 * <li>A comma-delimited list of anything on this list. 908 * </ul> 909 * 910 * <ul class='seealso'> 911 * <li class='link'>{@doc DynamicallyAppliedAnnotations} 912 * </ul> 913 */ 914 String on() default ""; 915}