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