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