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>@RestResource</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 * <h5 class='section'>See Also:</h5> 072 * <ul> 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 * <h5 class='section'>Notes:</h5> 088 * <ul class='spaced-list'> 089 * <li> 090 * The format is a <a href='https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03'>JSON Reference</a>. 091 * <li> 092 * Supports {@doc DefaultRestSvlVariables} 093 * (e.g. <js>"$L{my.localized.variable}"</js>). 094 * </ul> 095 */ 096 String $ref() default ""; 097 098 /** 099 * <mk>format</mk> field of the {@doc SwaggerSchemaObject}. 100 * 101 * <h5 class='section'>Examples:</h5> 102 * <p class='bcode w800'> 103 * <jc>// Used on parameter</jc> 104 * <ja>@RestMethod</ja>(name=<jsf>PUT</jsf>) 105 * <jk>public void</jk> setAge( 106 * <ja>@Body</ja>(type=<js>"integer"</js>, format=<js>"int32"</js>) String input 107 * ) {...} 108 * </p> 109 * 110 * <h5 class='section'>Notes:</h5> 111 * <ul class='spaced-list'> 112 * <li> 113 * The format is plain text. 114 * <li> 115 * Supports {@doc DefaultRestSvlVariables} 116 * (e.g. <js>"$L{my.localized.variable}"</js>). 117 * </ul> 118 * 119 * <h5 class='section'>See Also:</h5> 120 * <ul class='doctree'> 121 * <li class='extlink'>{@doc SwaggerDataTypeFormats} 122 * </ul> 123 */ 124 String format() default ""; 125 126 /** 127 * <mk>title</mk> field of the {@doc SwaggerSchemaObject}. 128 * 129 * <h5 class='section'>Notes:</h5> 130 * <ul class='spaced-list'> 131 * <li> 132 * The format is plain text. 133 * <li> 134 * Supports {@doc DefaultRestSvlVariables} 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 SwaggerSchemaObject}. 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 * <h5 class='section'>Notes:</h5> 164 * <ul class='spaced-list'> 165 * <li> 166 * The format is plain text. 167 * <br>Multiple lines are concatenated with newlines. 168 * <li> 169 * Supports {@doc DefaultRestSvlVariables} 170 * (e.g. <js>"$L{my.localized.variable}"</js>). 171 * </ul> 172 */ 173 String[] description() default {}; 174 175 /** 176 * <mk>default</mk> field of the {@doc SwaggerSchemaObject}. 177 * 178 * <h5 class='section'>Notes:</h5> 179 * <ul class='spaced-list'> 180 * <li> 181 * The format is any {@doc juneau-marshall.JsonDetails.SimplifiedJson}. 182 * <br>Multiple lines are concatenated with newlines. 183 * <li> 184 * Supports {@doc DefaultRestSvlVariables} 185 * (e.g. <js>"$L{my.localized.variable}"</js>). 186 * </ul> 187 */ 188 String[] _default() default {}; 189 190 /** 191 * <mk>multipleOf</mk> field of the {@doc SwaggerSchemaObject}. 192 * 193 * <h5 class='section'>Notes:</h5> 194 * <ul class='spaced-list'> 195 * <li> 196 * The format is numeric. 197 * <li> 198 * Supports {@doc DefaultRestSvlVariables} 199 * (e.g. <js>"$L{my.localized.variable}"</js>). 200 * </ul> 201 */ 202 String multipleOf() default ""; 203 204 /** 205 * <mk>maximum</mk> field of the {@doc SwaggerSchemaObject}. 206 * 207 * <h5 class='section'>Notes:</h5> 208 * <ul class='spaced-list'> 209 * <li> 210 * The format is numeric. 211 * <li> 212 * Supports {@doc DefaultRestSvlVariables} 213 * (e.g. <js>"$L{my.localized.variable}"</js>). 214 * </ul> 215 */ 216 String maximum() default ""; 217 218 /** 219 * <mk>exclusiveMaximum</mk> field of the {@doc SwaggerSchemaObject}. 220 * 221 * <h5 class='section'>Notes:</h5> 222 * <ul class='spaced-list'> 223 * <li> 224 * The format is numeric. 225 * <li> 226 * Supports {@doc DefaultRestSvlVariables} 227 * (e.g. <js>"$L{my.localized.variable}"</js>). 228 * </ul> 229 */ 230 boolean exclusiveMaximum() default false; 231 232 /** 233 * <mk>minimum</mk> field of the {@doc SwaggerSchemaObject}. 234 * 235 * <h5 class='section'>Notes:</h5> 236 * <ul class='spaced-list'> 237 * <li> 238 * The format is numeric. 239 * <li> 240 * Supports {@doc DefaultRestSvlVariables} 241 * (e.g. <js>"$L{my.localized.variable}"</js>). 242 * </ul> 243 */ 244 String minimum() default ""; 245 246 /** 247 * <mk>exclusiveMinimum</mk> field of the {@doc SwaggerSchemaObject}. 248 * 249 * <h5 class='section'>Notes:</h5> 250 * <ul class='spaced-list'> 251 * <li> 252 * The format is numeric. 253 * <li> 254 * Supports {@doc DefaultRestSvlVariables} 255 * (e.g. <js>"$L{my.localized.variable}"</js>). 256 * </ul> 257 */ 258 boolean exclusiveMinimum() default false; 259 260 /** 261 * <mk>maxLength</mk> field of the {@doc SwaggerSchemaObject}. 262 * 263 * <h5 class='section'>Notes:</h5> 264 * <ul class='spaced-list'> 265 * <li> 266 * The format is numeric. 267 * <li> 268 * Supports {@doc DefaultRestSvlVariables} 269 * (e.g. <js>"$L{my.localized.variable}"</js>). 270 * </ul> 271 */ 272 long maxLength() default -1; 273 274 /** 275 * <mk>minLength</mk> field of the {@doc SwaggerSchemaObject}. 276 * 277 * <h5 class='section'>Notes:</h5> 278 * <ul class='spaced-list'> 279 * <li> 280 * The format is numeric. 281 * <li> 282 * Supports {@doc DefaultRestSvlVariables} 283 * (e.g. <js>"$L{my.localized.variable}"</js>). 284 * </ul> 285 */ 286 long minLength() default -1; 287 288 /** 289 * <mk>pattern</mk> field of the {@doc SwaggerSchemaObject}. 290 * 291 * <h5 class='section'>Example:</h5> 292 * <p class='bcode w800'> 293 * <ja>@RestMethod</ja>(name=<jsf>PUT</jsf>) 294 * <jk>public void</jk> doPut(<ja>@Body</ja>(format=<js>"/\\w+\\.\\d+/"</js>) String input) {...} 295 * </p> 296 * 297 * <h5 class='section'>Notes:</h5> 298 * <ul class='spaced-list'> 299 * <li> 300 * The format is plain text. 301 * <li> 302 * This string SHOULD be a valid regular expression. 303 * <li> 304 * Supports {@doc DefaultRestSvlVariables} 305 * (e.g. <js>"$L{my.localized.variable}"</js>). 306 * </ul> 307 */ 308 String pattern() default ""; 309 310 /** 311 * <mk>maxItems</mk> field of the {@doc SwaggerSchemaObject}. 312 * 313 * <h5 class='section'>Notes:</h5> 314 * <ul class='spaced-list'> 315 * <li> 316 * The format is numeric. 317 * <li> 318 * Supports {@doc DefaultRestSvlVariables} 319 * (e.g. <js>"$L{my.localized.variable}"</js>). 320 * </ul> 321 */ 322 long maxItems() default -1; 323 324 /** 325 * <mk>minItems</mk> field of the {@doc SwaggerSchemaObject}. 326 * 327 * <h5 class='section'>Notes:</h5> 328 * <ul class='spaced-list'> 329 * <li> 330 * The format is numeric. 331 * <li> 332 * Supports {@doc DefaultRestSvlVariables} 333 * (e.g. <js>"$L{my.localized.variable}"</js>). 334 * </ul> 335 */ 336 long minItems() default -1; 337 338 /** 339 * <mk>uniqueItems</mk> field of the {@doc SwaggerSchemaObject}. 340 * 341 * <h5 class='section'>Notes:</h5> 342 * <ul class='spaced-list'> 343 * <li> 344 * The format is boolean. 345 * <li> 346 * Supports {@doc DefaultRestSvlVariables} 347 * (e.g. <js>"$L{my.localized.variable}"</js>). 348 * </ul> 349 */ 350 boolean uniqueItems() default false; 351 352 353 /** 354 * <mk>maxProperties</mk> field of the {@doc SwaggerSchemaObject}. 355 * 356 * <h5 class='section'>Notes:</h5> 357 * <ul class='spaced-list'> 358 * <li> 359 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 360 * <br>Multiple lines are concatenated with newlines. 361 * <li> 362 * Supports {@doc DefaultRestSvlVariables} 363 * (e.g. <js>"$L{my.localized.variable}"</js>). 364 * </ul> 365 */ 366 long maxProperties() default -1; 367 368 369 /** 370 * <mk>minProperties</mk> field of the {@doc SwaggerSchemaObject}. 371 * 372 * <h5 class='section'>Notes:</h5> 373 * <ul class='spaced-list'> 374 * <li> 375 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 376 * <br>Multiple lines are concatenated with newlines. 377 * <li> 378 * Supports {@doc DefaultRestSvlVariables} 379 * (e.g. <js>"$L{my.localized.variable}"</js>). 380 * </ul> 381 */ 382 long minProperties() default -1; 383 384 /** 385 * <mk>required</mk> field of the {@doc SwaggerSchemaObject}. 386 * 387 * <p> 388 * Determines whether this parameter is mandatory. 389 * <br>The property MAY be included and its default value is false. 390 * 391 * <h5 class='section'>Examples:</h5> 392 * <p class='bcode w800'> 393 * <jc>// Used on parameter</jc> 394 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 395 * <jk>public void</jk> addPet( 396 * <ja>@Body</ja>(required=<jk>true</jk>) Pet input 397 * ) {...} 398 * </p> 399 * <p class='bcode w800'> 400 * <jc>// Used on class</jc> 401 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 402 * <jk>public void</jk> addPet(Pet input) {...} 403 * 404 * <ja>@Body</ja>(required=<jk>true</jk>) 405 * <jk>public class</jk> Pet {...} 406 * </p> 407 * 408 * <h5 class='section'>Notes:</h5> 409 * <ul class='spaced-list'> 410 * <li> 411 * The format is boolean. 412 * <li> 413 * Supports {@doc DefaultRestSvlVariables} 414 * (e.g. <js>"$L{my.localized.variable}"</js>). 415 * </ul> 416 */ 417 boolean required() default false; 418 419 /** 420 * <mk>enum</mk> field of the {@doc SwaggerSchemaObject}. 421 * 422 * <h5 class='section'>Notes:</h5> 423 * <ul class='spaced-list'> 424 * <li> 425 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} array or comma-delimited list. 426 * <br>Multiple lines are concatenated with newlines. 427 * <li> 428 * Supports {@doc DefaultRestSvlVariables} 429 * (e.g. <js>"$L{my.localized.variable}"</js>). 430 * </ul> 431 */ 432 String[] _enum() default {}; 433 434 /** 435 * <mk>type</mk> field of the {@doc SwaggerSchemaObject}. 436 * 437 * <h5 class='section'>Examples:</h5> 438 * <p class='bcode w800'> 439 * <jc>// Used on parameter</jc> 440 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 441 * <jk>public void</jk> addPet( 442 * <ja>@Body</ja>(type=<js>"object"</js>) Pet input 443 * ) {...} 444 * </p> 445 * <p class='bcode w800'> 446 * <jc>// Used on class</jc> 447 * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>) 448 * <jk>public void</jk> addPet(Pet input) {...} 449 * 450 * <ja>@Body</ja>(type=<js>"object"</js>) 451 * <jk>public class</jk> Pet {...} 452 * </p> 453 * 454 * <h5 class='section'>Notes:</h5> 455 * <ul class='spaced-list'> 456 * <li> 457 * The format is plain text. 458 * <li> 459 * The possible values are: 460 * <ul> 461 * <li><js>"object"</js> 462 * <li><js>"string"</js> 463 * <li><js>"number"</js> 464 * <li><js>"integer"</js> 465 * <li><js>"boolean"</js> 466 * <li><js>"array"</js> 467 * <li><js>"file"</js> 468 * </ul> 469 * <li> 470 * Supports {@doc DefaultRestSvlVariables} 471 * (e.g. <js>"$L{my.localized.variable}"</js>). 472 * </ul> 473 * 474 * <h5 class='section'>See Also:</h5> 475 * <ul class='doctree'> 476 * <li class='extlink'>{@doc SwaggerDataTypes} 477 * </ul> 478 * 479 */ 480 String type() default ""; 481 482 /** 483 * <mk>items</mk> field of the {@doc SwaggerSchemaObject}. 484 * 485 * <h5 class='section'>Notes:</h5> 486 * <ul class='spaced-list'> 487 * <li> 488 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 489 * <br>Multiple lines are concatenated with newlines. 490 * <li> 491 * Supports {@doc DefaultRestSvlVariables} 492 * (e.g. <js>"$L{my.localized.variable}"</js>). 493 * </ul> 494 */ 495 Items items() default @Items; 496 497 /** 498 * <mk>collectionFormat</mk> field. 499 * 500 * <p> 501 * Note that this field isn't part of the Swagger 2.0 specification, but the specification does not specify how 502 * items are supposed to be represented. 503 * 504 * <p> 505 * Determines the format of the array if <code>type</code> <js>"array"</js> is used. 506 * <br>Can only be used if <code>type</code> is <js>"array"</js>. 507 * 508 * <br>Possible values are: 509 * <ul class='spaced-list'> 510 * <li> 511 * <js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>). 512 * <li> 513 * <js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>). 514 * <li> 515 * <js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>). 516 * <li> 517 * <js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>). 518 * <li> 519 * <js>"multi"</js> - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&foo=baz"</js>). 520 * <li> 521 * <js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>). 522 * </ul> 523 * 524 * <p> 525 * Static strings are defined in {@link CollectionFormatType}. 526 * 527 * <p> 528 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 529 * 530 * <h5 class='section'>Used for:</h5> 531 * <ul class='spaced-list'> 532 * <li> 533 * Server-side schema-based parsing. 534 * <li> 535 * Server-side generated Swagger documentation. 536 * <li> 537 * Client-side schema-based serializing. 538 * </ul> 539 */ 540 String collectionFormat() default ""; 541 542 /** 543 * <mk>allOf</mk> field of the {@doc SwaggerSchemaObject}. 544 * 545 * <h5 class='section'>Notes:</h5> 546 * <ul class='spaced-list'> 547 * <li> 548 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 549 * <br>Multiple lines are concatenated with newlines. 550 * <li> 551 * Supports {@doc DefaultRestSvlVariables} 552 * (e.g. <js>"$L{my.localized.variable}"</js>). 553 * </ul> 554 */ 555 String[] allOf() default {}; 556 557 /** 558 * <mk>properties</mk> field of the {@doc SwaggerSchemaObject}. 559 * 560 * <h5 class='section'>Notes:</h5> 561 * <ul class='spaced-list'> 562 * <li> 563 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 564 * <br>Multiple lines are concatenated with newlines. 565 * <li> 566 * Supports {@doc DefaultRestSvlVariables} 567 * (e.g. <js>"$L{my.localized.variable}"</js>). 568 * </ul> 569 */ 570 String[] properties() default {}; 571 572 /** 573 * <mk>additionalProperties</mk> field of the {@doc SwaggerSchemaObject}. 574 * 575 * <h5 class='section'>Notes:</h5> 576 * <ul class='spaced-list'> 577 * <li> 578 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 579 * <br>Multiple lines are concatenated with newlines. 580 * <li> 581 * Supports {@doc DefaultRestSvlVariables} 582 * (e.g. <js>"$L{my.localized.variable}"</js>). 583 * </ul> 584 */ 585 String[] additionalProperties() default {}; 586 587 /** 588 * <mk>discriminator</mk> field of the {@doc SwaggerSchemaObject}. 589 * 590 * <h5 class='section'>Notes:</h5> 591 * <ul class='spaced-list'> 592 * <li> 593 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} 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 discriminator() default ""; 601 602 /** 603 * <mk>readOnly</mk> field of the {@doc SwaggerSchemaObject}. 604 * 605 * <h5 class='section'>Notes:</h5> 606 * <ul class='spaced-list'> 607 * <li> 608 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 609 * <br>Multiple lines are concatenated with newlines. 610 * <li> 611 * Supports {@doc DefaultRestSvlVariables} 612 * (e.g. <js>"$L{my.localized.variable}"</js>). 613 * </ul> 614 */ 615 boolean readOnly() default false; 616 617 /** 618 * <mk>xml</mk> field of the {@doc SwaggerSchemaObject}. 619 * 620 * <h5 class='section'>Notes:</h5> 621 * <ul class='spaced-list'> 622 * <li> 623 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 624 * <br>Multiple lines are concatenated with newlines. 625 * <li> 626 * Supports {@doc DefaultRestSvlVariables} 627 * (e.g. <js>"$L{my.localized.variable}"</js>). 628 * </ul> 629 */ 630 String[] xml() default {}; 631 632 /** 633 * <mk>externalDocs</mk> field of the {@doc SwaggerSchemaObject}. 634 * 635 * <h5 class='section'>Notes:</h5> 636 * <ul class='spaced-list'> 637 * <li> 638 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 639 * <br>Multiple lines are concatenated with newlines. 640 * <li> 641 * Supports {@doc DefaultRestSvlVariables} 642 * (e.g. <js>"$L{my.localized.variable}"</js>). 643 * </ul> 644 */ 645 ExternalDocs externalDocs() default @ExternalDocs; 646 647 /** 648 * <mk>example</mk> field of the {@doc SwaggerSchemaObject}. 649 * 650 * <p> 651 * A free-form property to include an example of an instance for this schema. 652 * 653 * <p> 654 * This attribute defines a JSON representation of the body value that is used by <code>BasicRestInfoProvider</code> to construct 655 * media-type-based examples of the body of the request. 656 * 657 * <h5 class='section'>Notes:</h5> 658 * <ul class='spaced-list'> 659 * <li> 660 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object or plain text string. 661 * <br>Multiple lines are concatenated with newlines. 662 * <li> 663 * Supports {@doc DefaultRestSvlVariables} 664 * (e.g. <js>"$L{my.localized.variable}"</js>). 665 * </ul> 666 */ 667 String[] example() default {}; 668 669 /** 670 * <mk>x-examples</mk> field of the {@doc SwaggerSchemaObject}. 671 * 672 * <p> 673 * This is a JSON object whose keys are media types and values are string representations of that value. 674 * 675 * <h5 class='section'>Notes:</h5> 676 * <ul class='spaced-list'> 677 * <li> 678 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 679 * <br>Multiple lines are concatenated with newlines. 680 * <li> 681 * Supports {@doc DefaultRestSvlVariables} 682 * (e.g. <js>"$L{my.localized.variable}"</js>). 683 * </ul> 684 */ 685 String[] examples() default {}; 686 687 /** 688 * Specifies that schema information for this part should not be shown in the generated Swagger documentation. 689 */ 690 boolean ignore() default false; 691 692 /** 693 * Free-form value for the {@doc SwaggerSchemaObject}. 694 * 695 * <p> 696 * This is a JSON object that makes up the swagger information for this field. 697 * 698 * <p> 699 * The following are completely equivalent ways of defining the swagger description of a Schema object: 700 * <p class='bcode w800'> 701 * <jc>// Normal</jc> 702 * <ja>@Schema</ja>( 703 * type=<js>"array"</js>, 704 * items=<ja>@Items</ja>( 705 * $ref=<js>"#/definitions/Pet"</js> 706 * ) 707 * ) 708 * </p> 709 * <p class='bcode w800'> 710 * <jc>// Free-form</jc> 711 * <ja>@Schema</ja>( 712 * <js>"type: 'array',"</js>, 713 * <js>"items: {"</js>, 714 * <js>"$ref: '#/definitions/Pet'"</js>, 715 * <js>"}"</js> 716 * ) 717 * </p> 718 * <p class='bcode w800'> 719 * <jc>// Free-form using variables</jc> 720 * <ja>@Schema</ja>(<js>"$L{petArraySwagger}"</js>) 721 * </p> 722 * <p class='bcode w800'> 723 * <mc>// Contents of MyResource.properties</mc> 724 * <mk>petArraySwagger</mk> = <mv>{ type: "array", items: { $ref: "#/definitions/Pet" } }</mv> 725 * </p> 726 * 727 * <p> 728 * The reasons why you may want to use this field include: 729 * <ul> 730 * <li>You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file. 731 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 732 * </ul> 733 * 734 * <h5 class='section'>Notes:</h5> 735 * <ul class='spaced-list'> 736 * <li> 737 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 738 * <li> 739 * The leading/trailing <code>{ }</code> characters are optional. 740 * <br>The following two example are considered equivalent: 741 * <p class='bcode w800'> 742 * <ja>@Schema</ja>(<js>"{type: 'array'}"</js>) 743 * </p> 744 * <p class='bcode w800'> 745 * <ja>@Schema</ja>(<js>"type: 'array'"</js>) 746 * </p> 747 * <li> 748 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 749 * <li> 750 * Supports {@doc DefaultRestSvlVariables} 751 * (e.g. <js>"$L{my.localized.variable}"</js>). 752 * <li> 753 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 754 * </ul> 755 */ 756 String[] value() default {}; 757}