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.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019import java.util.*; 020 021import org.apache.juneau.jsonschema.annotation.Items; 022import org.apache.juneau.*; 023import org.apache.juneau.annotation.*; 024import org.apache.juneau.collections.*; 025import org.apache.juneau.httppart.*; 026import org.apache.juneau.json.*; 027import org.apache.juneau.jsonschema.*; 028import org.apache.juneau.oapi.*; 029 030/** 031 * REST request form-data annotation. 032 * 033 * <p> 034 * Identifies a POJO to be used as a form-data entry on an HTTP request. 035 * 036 * <p> 037 * Can be used in the following locations: 038 * <ul> 039 * <li>Arguments and argument-types of server-side <ja>@RestMethod</ja>-annotated methods. 040 * <li>Arguments and argument-types of client-side <ja>@RemoteResource</ja>-annotated interfaces. 041 * <li>Methods and return types of server-side and client-side <ja>@Request</ja>-annotated interfaces. 042 * </ul> 043 * 044 * <h5 class='topic'>Arguments and argument-types of server-side @RestMethod-annotated methods</h5> 045 * 046 * Annotation that can be applied to a parameter of a <ja>@RestMethod</ja>-annotated method to identify it as a URL query parameter. 047 * 048 * <p> 049 * Unlike {@link FormData @FormData}, using this annotation does not result in the servlet reading the contents of 050 * URL-encoded form posts. 051 * Therefore, this annotation can be used in conjunction with the {@link Body @Body} annotation or 052 * <c>RestRequest.getBody()</c> method for <c>application/x-www-form-urlencoded POST</c> calls. 053 * 054 * <h5 class='section'>Example:</h5> 055 * <p class='bcode w800'> 056 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>) 057 * <jk>public void</jk> doGet( 058 * <ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> p1, 059 * <ja>@Query</ja>(<js>"p2"</js>) String p2, 060 * <ja>@Query</ja>(<js>"p3"</js>) UUID p3 061 * ) {...} 062 * </p> 063 * 064 * <p> 065 * This is functionally equivalent to the following code... 066 * <p class='bcode w800'> 067 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>) 068 * <jk>public void</jk> doGet(RestRequest req, RestResponse res) { 069 * <jk>int</jk> p1 = req.getQueryParameter(<jk>int</jk>.<jk>class</jk>, <js>"p1"</js>, 0); 070 * String p2 = req.getQueryParameter(String.<jk>class</jk>, <js>"p2"</js>); 071 * UUID p3 = req.getQueryParameter(UUID.<jk>class</jk>, <js>"p3"</js>); 072 * ... 073 * } 074 * </p> 075 * 076 * <ul class='seealso'> 077 * <li class='link'>{@doc RestQueryAnnotation} 078 * <li class='link'>{@doc RestSwagger} 079 * <li class='extlink'>{@doc ExtSwaggerParameterObject} 080 * </ul> 081 * 082 * <h5 class='topic'>Arguments and argument-types of client-side @RemoteResource-annotated interfaces</h5> 083 * 084 * <ul class='seealso'> 085 * <li class='link'>{@doc RestcQuery} 086 * </ul> 087 * 088 * <h5 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h5> 089 * 090 * <ul class='seealso'> 091 * <li class='link'>{@doc RestRequestAnnotation} 092 * <li class='link'>{@doc RestcRequest} 093 * </ul> 094 */ 095@Documented 096@Target({PARAMETER,FIELD,METHOD,TYPE}) 097@Retention(RUNTIME) 098@Inherited 099public @interface Query { 100 101 /** 102 * Skips this value during serialization if it's an empty string or empty collection/array. 103 * 104 * <p> 105 * Note that <jk>null</jk> values are already ignored. 106 * 107 * <h5 class='section'>Used for:</h5> 108 * <ul class='spaced-list'> 109 * <li> 110 * Client-side schema-based serializing. 111 * </ul> 112 */ 113 boolean skipIfEmpty() default false; 114 115 /** 116 * Synonym for {@link #skipIfEmpty()}. 117 */ 118 boolean sie() default false; 119 120 /** 121 * Specifies the {@link HttpPartSerializer} class used for serializing values to strings. 122 * 123 * <p> 124 * Overrides for this part the part serializer defined on the REST client which by default is {@link OpenApiSerializer}. 125 */ 126 Class<? extends HttpPartSerializer> serializer() default HttpPartSerializer.Null.class; 127 128 /** 129 * Specifies the {@link HttpPartParser} class used for parsing strings to values. 130 * 131 * <p> 132 * Overrides for this part the part parser defined on the REST resource which by default is {@link OpenApiParser}. 133 */ 134 Class<? extends HttpPartParser> parser() default HttpPartParser.Null.class; 135 136 /** 137 * Denotes a multi-part parameter (e.g. multiple entries with the same name). 138 * 139 * <h5 class='figure'>Example</h5> 140 * <jk>public void</jk> doPost( 141 * <ja>@Query</ja>(name=<js>"beans"</js>, multi=<jk>true</jk>) MyBean[] beans 142 * ) { 143 * 144 * <ul class='notes'> 145 * <li> 146 * Meant to be used on multi-part parameters (e.g. <js>"key=1&key=2&key=3"</js> instead of <js>"key=@(1,2,3)"</js>) 147 * <li> 148 * The data type must be a collection or array type. 149 * </ul> 150 */ 151 boolean multi() default false; 152 153 //================================================================================================================= 154 // Attributes common to all Swagger Parameter objects 155 //================================================================================================================= 156 157 /** 158 * URL query parameter name. 159 * 160 * Required. The name of the parameter. Parameter names are case sensitive. 161 * 162 * <p> 163 * The value should be either a valid query parameter name, or <js>"*"</js> to represent multiple name/value pairs 164 * 165 * <p> 166 * A blank value (the default) has the following behavior: 167 * <ul class='spaced-list'> 168 * <li> 169 * If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean, 170 * then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs. 171 * 172 * <h5 class='figure'>Examples:</h5> 173 * <p class='bcode w800'> 174 * <jc>// When used on a REST method</jc> 175 * <ja>@RestMethod</ja>(path=<js>"/addPet"</js>) 176 * <jk>public void</jk> addPet(<ja>@Query</ja> OMap allQueryParameters) {...} 177 * </p> 178 * <p class='bcode w800'> 179 * <jc>// When used on a remote method parameter</jc> 180 * <ja>@RemoteResource</ja>(path=<js>"/myproxy"</js>) 181 * <jk>public interface</jk> MyProxy { 182 * 183 * <jc>// Equivalent to @Query("*")</jc> 184 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod"</js>) 185 * String myProxyMethod1(<ja>@Query</ja> Map<String,Object> allQueryParameters); 186 * } 187 * </p> 188 * <p class='bcode w800'> 189 * <jc>// When used on a request bean method</jc> 190 * <jk>public interface</jk> MyRequest { 191 * 192 * <jc>// Equivalent to @Query("*")</jc> 193 * <ja>@Query</ja> 194 * Map<String,Object> getFoo(); 195 * } 196 * </p> 197 * </li> 198 * <li> 199 * If used on a request bean method, uses the bean property name. 200 * 201 * <h5 class='figure'>Example:</h5> 202 * <p class='bcode w800'> 203 * <jk>public interface</jk> MyRequest { 204 * 205 * <jc>// Equivalent to @Query("foo")</jc> 206 * <ja>@Query</ja> 207 * String getFoo(); 208 * } 209 * </p> 210 * </li> 211 * </ul> 212 * <ul class='notes'> 213 * <li> 214 * The format is plain-text. 215 * </ul> 216 */ 217 String name() default ""; 218 219 /** 220 * Synonym for {@link #name()}. 221 */ 222 String n() default ""; 223 224 /** 225 * A synonym for {@link #name()}. 226 * 227 * <p> 228 * Allows you to use shortened notation if you're only specifying the name. 229 * 230 * <p> 231 * The following are completely equivalent ways of defining the existence of a query entry: 232 * <p class='bcode w800'> 233 * <jk>public</jk> Order placeOrder(<ja>@Query</ja>(name=<js>"petId"</js>) <jk>long</jk> petId) {...} 234 * </p> 235 * <p class='bcode w800'> 236 * <jk>public</jk> Order placeOrder(<ja>@Query</ja>(<js>"petId"</js>) <jk>long</jk> petId) {...} 237 * </p> 238 */ 239 String value() default ""; 240 241 /** 242 * <mk>description</mk> field of the {@doc ExtSwaggerParameterObject}. 243 * 244 * <p> 245 * A brief description of the parameter. This could contain examples of use. 246 * 247 * <h5 class='section'>Used for:</h5> 248 * <ul class='spaced-list'> 249 * <li> 250 * Server-side generated Swagger documentation. 251 * </ul> 252 * 253 * <ul class='notes'> 254 * <li> 255 * The format is plain text. 256 * <br>Multiple lines are concatenated with newlines. 257 * <li> 258 * Supports {@doc RestSvlVariables} 259 * (e.g. <js>"$L{my.localized.variable}"</js>). 260 * </ul> 261 */ 262 String[] description() default {}; 263 264 /** 265 * Synonym for {@link #description()}. 266 */ 267 String[] d() default {}; 268 269 /** 270 * <mk>required</mk> field of the {@doc ExtSwaggerParameterObject}. 271 * 272 * <p> 273 * Determines whether the parameter is mandatory. 274 * 275 * <p> 276 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 277 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 278 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 279 * 280 * <h5 class='section'>Used for:</h5> 281 * <ul class='spaced-list'> 282 * <li> 283 * Server-side schema-based parsing validation. 284 * <li> 285 * Server-side generated Swagger documentation. 286 * <li> 287 * Client-side schema-based serializing validation. 288 * </ul> 289 */ 290 boolean required() default false; 291 292 /** 293 * Synonym for {@link #required()}. 294 */ 295 boolean r() default false; 296 297 //================================================================================================================= 298 // Attributes specific to parameters other than body 299 //================================================================================================================= 300 301 /** 302 * <mk>type</mk> field of the {@doc ExtSwaggerParameterObject}. 303 * 304 * <p> 305 * The type of the parameter. 306 * 307 * <p> 308 * The possible values are: 309 * <ul class='spaced-list'> 310 * <li> 311 * <js>"string"</js> 312 * <br>Parameter must be a string or a POJO convertible from a string. 313 * <li> 314 * <js>"number"</js> 315 * <br>Parameter must be a number primitive or number object. 316 * <br>If parameter is <c>Object</c>, creates either a <c>Float</c> or <c>Double</c> depending on the size of the number. 317 * <li> 318 * <js>"integer"</js> 319 * <br>Parameter must be a integer/long primitive or integer/long object. 320 * <br>If parameter is <c>Object</c>, creates either a <c>Short</c>, <c>Integer</c>, or <c>Long</c> depending on the size of the number. 321 * <li> 322 * <js>"boolean"</js> 323 * <br>Parameter must be a boolean primitive or object. 324 * <li> 325 * <js>"array"</js> 326 * <br>Parameter must be an array or collection. 327 * <br>Elements must be strings or POJOs convertible from strings. 328 * <br>If parameter is <c>Object</c>, creates an {@link OList}. 329 * <li> 330 * <js>"object"</js> 331 * <br>Parameter must be a map or bean. 332 * <br>If parameter is <c>Object</c>, creates an {@link OMap}. 333 * <br>Note that this is an extension of the OpenAPI schema as Juneau allows for arbitrarily-complex POJOs to be serialized as HTTP parts. 334 * <li> 335 * <js>"file"</js> 336 * <br>This type is currently not supported. 337 * </ul> 338 * 339 * <p> 340 * Static strings are defined in {@link ParameterType}. 341 * 342 * <h5 class='section'>Used for:</h5> 343 * <ul class='spaced-list'> 344 * <li> 345 * Server-side schema-based parsing. 346 * <li> 347 * Server-side generated Swagger documentation. 348 * <li> 349 * Client-side schema-based serializing. 350 * </ul> 351 * 352 * <ul class='seealso'> 353 * <li class='extlink'>{@doc ExtSwaggerDataTypes} 354 * </ul> 355 */ 356 String type() default ""; 357 358 /** 359 * Synonym for {@link #type()}. 360 */ 361 String t() default ""; 362 363 /** 364 * <mk>format</mk> field of the {@doc ExtSwaggerParameterObject}. 365 * 366 * <p> 367 * The extending format for the previously mentioned {@doc ExtSwaggerParameterTypes parameter type}. 368 * 369 * <p> 370 * The possible values are: 371 * <ul class='spaced-list'> 372 * <li> 373 * <js>"int32"</js> - Signed 32 bits. 374 * <br>Only valid with type <js>"integer"</js>. 375 * <li> 376 * <js>"int64"</js> - Signed 64 bits. 377 * <br>Only valid with type <js>"integer"</js>. 378 * <li> 379 * <js>"float"</js> - 32-bit floating point number. 380 * <br>Only valid with type <js>"number"</js>. 381 * <li> 382 * <js>"double"</js> - 64-bit floating point number. 383 * <br>Only valid with type <js>"number"</js>. 384 * <li> 385 * <js>"byte"</js> - BASE-64 encoded characters. 386 * <br>Only valid with type <js>"string"</js>. 387 * <br>Parameters of type POJO convertible from string are converted after the string has been decoded. 388 * <li> 389 * <js>"binary"</js> - Hexadecimal encoded octets (e.g. <js>"00FF"</js>). 390 * <br>Only valid with type <js>"string"</js>. 391 * <br>Parameters of type POJO convertible from string are converted after the string has been decoded. 392 * <li> 393 * <js>"date"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>. 394 * <br>Only valid with type <js>"string"</js>. 395 * <li> 396 * <js>"date-time"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>. 397 * <br>Only valid with type <js>"string"</js>. 398 * <li> 399 * <js>"password"</js> - Used to hint UIs the input needs to be obscured. 400 * <br>This format does not affect the serialization or parsing of the parameter. 401 * <li> 402 * <js>"uon"</js> - UON notation (e.g. <js>"(foo=bar,baz=@(qux,123))"</js>). 403 * <br>Only valid with type <js>"object"</js>. 404 * <br>If not specified, then the input is interpreted as plain-text and is converted to a POJO directly. 405 * </ul> 406 * 407 * <p> 408 * Static strings are defined in {@link FormatType}. 409 * 410 * <h5 class='section'>Used for:</h5> 411 * <ul class='spaced-list'> 412 * <li> 413 * Server-side schema-based parsing. 414 * <li> 415 * Server-side generated Swagger documentation. 416 * <li> 417 * Client-side schema-based serializing. 418 * </ul> 419 * 420 * <ul class='seealso'> 421 * <li class='extlink'>{@doc ExtSwaggerDataTypeFormats} 422 * </ul> 423 */ 424 String format() default ""; 425 426 /** 427 * Synonym for {@link #format()}. 428 */ 429 String f() default ""; 430 431 /** 432 * <mk>allowEmptyValue</mk> field of the {@doc ExtSwaggerParameterObject}. 433 * 434 * <p> 435 * Sets the ability to pass empty-valued parameters. 436 * <br>This is valid only for either query or formData parameters and allows you to send a parameter with a name only or an empty value. 437 * 438 * <p> 439 * The default value is <jk>false</jk>. 440 * 441 * <h5 class='section'>Used for:</h5> 442 * <ul class='spaced-list'> 443 * <li> 444 * Server-side schema-based parsing validation. 445 * <li> 446 * Server-side generated Swagger documentation. 447 * <li> 448 * Client-side schema-based serializing validation. 449 * </ul> 450 */ 451 boolean allowEmptyValue() default false; 452 453 /** 454 * Synonym for {@link #allowEmptyValue()}. 455 */ 456 boolean aev() default false; 457 458 /** 459 * <mk>items</mk> field of the {@doc ExtSwaggerParameterObject}. 460 * 461 * <p> 462 * Describes the type of items in the array. 463 * 464 * <p> 465 * Required if <c>type</c> is <js>"array"</js>. 466 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 467 * 468 * <h5 class='section'>Used for:</h5> 469 * <ul class='spaced-list'> 470 * <li> 471 * Server-side schema-based parsing and parsing validation. 472 * <li> 473 * Server-side generated Swagger documentation. 474 * <li> 475 * Client-side schema-based serializing and serializing validation. 476 * </ul> 477 */ 478 Items items() default @Items; 479 480 /** 481 * <mk>collectionFormat</mk> field of the {@doc ExtSwaggerParameterObject}. 482 * 483 * <p> 484 * Determines the format of the array if <c>type</c> <js>"array"</js> is used. 485 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 486 * 487 * <br>Possible values are: 488 * <ul class='spaced-list'> 489 * <li> 490 * <js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>). 491 * <li> 492 * <js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>). 493 * <li> 494 * <js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>). 495 * <li> 496 * <js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>). 497 * <li> 498 * <js>"multi"</js> - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&foo=baz"</js>). 499 * <br>Note: This is not supported by {@link OpenApiSerializer}. 500 * <li> 501 * <js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>). 502 * </ul> 503 * 504 * <p> 505 * Static strings are defined in {@link CollectionFormatType}. 506 * 507 * <p> 508 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 509 * 510 * <h5 class='section'>Used for:</h5> 511 * <ul class='spaced-list'> 512 * <li> 513 * Server-side schema-based parsing. 514 * <li> 515 * Server-side generated Swagger documentation. 516 * <li> 517 * Client-side schema-based serializing. 518 * </ul> 519 */ 520 String collectionFormat() default ""; 521 522 /** 523 * Synonym for {@link #collectionFormat()}. 524 */ 525 String cf() default ""; 526 527 /** 528 * <mk>default</mk> field of the {@doc ExtSwaggerParameterObject}. 529 * 530 * <p> 531 * Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request. 532 * <br>(Note: "default" has no meaning for required parameters.) 533 * 534 * <p> 535 * Additionally, this value is used to create instances of POJOs that are then serialized as language-specific examples in the generated Swagger documentation 536 * if the examples are not defined in some other way. 537 * 538 * <p> 539 * The format of this value is a string. 540 * <br>Multiple lines are concatenated with newlines. 541 * 542 * <h5 class='section'>Examples:</h5> 543 * <p class='bcode w800'> 544 * <jk>public</jk> Order placeOrder( 545 * <ja>@Query</ja>(name=<js>"petId"</js>, _default=<js>"100"</js>) <jk>long</jk> petId, 546 * <ja>@Query</ja>(name=<js>"additionalInfo"</js>, format=<js>"uon"</js>, _default=<js>"(rushOrder=false)"</js>) AdditionalInfo additionalInfo, 547 * <ja>@Query</ja>(name=<js>"flags"</js>, collectionFormat=<js>"uon"</js>, _default=<js>"@(new-customer)"</js>) String[] flags 548 * ) {...} 549 * </p> 550 * 551 * <h5 class='section'>Used for:</h5> 552 * <ul class='spaced-list'> 553 * <li> 554 * Server-side schema-based parsing. 555 * <li> 556 * Server-side generated Swagger documentation. 557 * <li> 558 * Client-side schema-based serializing. 559 * </ul> 560 */ 561 String[] _default() default {}; 562 563 /** 564 * Synonym for {@link #_default()}. 565 */ 566 String[] df() default {}; 567 568 /** 569 * <mk>maximum</mk> field of the {@doc ExtSwaggerParameterObject}. 570 * 571 * <p> 572 * Defines the maximum value for a parameter of numeric types. 573 * <br>The value must be a valid JSON number. 574 * 575 * <p> 576 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 577 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 578 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 579 * 580 * <p> 581 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 582 * 583 * <h5 class='section'>Used for:</h5> 584 * <ul class='spaced-list'> 585 * <li> 586 * Server-side schema-based parsing validation. 587 * <li> 588 * Server-side generated Swagger documentation. 589 * <li> 590 * Client-side schema-based serializing validation. 591 * </ul> 592 */ 593 String maximum() default ""; 594 595 /** 596 * Synonym for {@link #maximum()}. 597 */ 598 String max() default ""; 599 600 /** 601 * <mk>exclusiveMaximum</mk> field of the {@doc ExtSwaggerParameterObject}. 602 * 603 * <p> 604 * Defines whether the maximum is matched exclusively. 605 * 606 * <p> 607 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 608 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 609 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 610 * 611 * <p> 612 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 613 * <br>If <jk>true</jk>, must be accompanied with <c>maximum</c>. 614 * 615 * <h5 class='section'>Used for:</h5> 616 * <ul class='spaced-list'> 617 * <li> 618 * Server-side schema-based parsing validation. 619 * <li> 620 * Server-side generated Swagger documentation. 621 * <li> 622 * Client-side schema-based serializing validation. 623 * </ul> 624 */ 625 boolean exclusiveMaximum() default false; 626 627 /** 628 * Synonym for {@link #exclusiveMaximum()}. 629 */ 630 boolean emax() default false; 631 632 /** 633 * <mk>minimum</mk> field of the {@doc ExtSwaggerParameterObject}. 634 * 635 * <p> 636 * Defines the minimum value for a parameter of numeric types. 637 * <br>The value must be a valid JSON number. 638 * 639 * <p> 640 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 641 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 642 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 643 * 644 * <p> 645 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 646 * 647 * <h5 class='section'>Used for:</h5> 648 * <ul class='spaced-list'> 649 * <li> 650 * Server-side schema-based parsing validation. 651 * <li> 652 * Server-side generated Swagger documentation. 653 * <li> 654 * Client-side schema-based serializing validation. 655 * </ul> 656 */ 657 String minimum() default ""; 658 659 /** 660 * Synonym for {@link #minimum()}. 661 */ 662 String min() default ""; 663 664 /** 665 * <mk>exclusiveMinimum</mk> field of the {@doc ExtSwaggerParameterObject}. 666 * 667 * <p> 668 * Defines whether the minimum is matched exclusively. 669 * 670 * <p> 671 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 672 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 673 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 674 * 675 * <p> 676 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 677 * <br>If <jk>true</jk>, Must be accompanied with <c>minimum</c>. 678 * 679 * <h5 class='section'>Used for:</h5> 680 * <ul class='spaced-list'> 681 * <li> 682 * Server-side schema-based parsing validation. 683 * <li> 684 * Server-side generated Swagger documentation. 685 * <li> 686 * Client-side schema-based serializing validation. 687 * </ul> 688 */ 689 boolean exclusiveMinimum() default false; 690 691 /** 692 * Synonym for {@link #exclusiveMinimum()}. 693 */ 694 boolean emin() default false; 695 696 /** 697 * <mk>maxLength</mk> field of the {@doc ExtSwaggerParameterObject}. 698 * 699 * <p> 700 * A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword. 701 * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>. 702 * <br>The value <c>-1</c> is always ignored. 703 * 704 * <p> 705 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 706 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 707 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 708 * 709 * <p> 710 * Only allowed for the following types: <js>"string"</js>. 711 * 712 * <h5 class='section'>Used for:</h5> 713 * <ul class='spaced-list'> 714 * <li> 715 * Server-side schema-based parsing validation. 716 * <li> 717 * Server-side generated Swagger documentation. 718 * <li> 719 * Client-side schema-based serializing validation. 720 * </ul> 721 */ 722 long maxLength() default -1; 723 724 /** 725 * Synonym for {@link #maxLength()}. 726 */ 727 long maxl() default -1; 728 729 /** 730 * <mk>minLength</mk> field of the {@doc ExtSwaggerParameterObject}. 731 * 732 * <p> 733 * A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword. 734 * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>. 735 * <br>The value <c>-1</c> is always ignored. 736 * 737 * <p> 738 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 739 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 740 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 741 * 742 * <p> 743 * Only allowed for the following types: <js>"string"</js>. 744 * 745 * <h5 class='section'>Used for:</h5> 746 * <ul class='spaced-list'> 747 * <li> 748 * Server-side schema-based parsing validation. 749 * <li> 750 * Server-side generated Swagger documentation. 751 * <li> 752 * Client-side schema-based serializing validation. 753 * </ul> 754 */ 755 long minLength() default -1; 756 757 /** 758 * Synonym for {@link #minLength()}. 759 */ 760 long minl() default -1; 761 762 /** 763 * <mk>pattern</mk> field of the {@doc ExtSwaggerParameterObject}. 764 * 765 * <p> 766 * A string input is valid if it matches the specified regular expression pattern. 767 * 768 * <p> 769 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 770 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 771 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 772 * 773 * <p> 774 * Only allowed for the following types: <js>"string"</js>. 775 * 776 * <h5 class='section'>Used for:</h5> 777 * <ul class='spaced-list'> 778 * <li> 779 * Server-side schema-based parsing validation. 780 * <li> 781 * Server-side generated Swagger documentation. 782 * <li> 783 * Client-side schema-based serializing validation. 784 * </ul> 785 */ 786 String pattern() default ""; 787 788 /** 789 * Synonym for {@link #pattern()}. 790 */ 791 String p() default ""; 792 793 /** 794 * <mk>maxItems</mk> field of the {@doc ExtSwaggerParameterObject}. 795 * 796 * <p> 797 * An array or collection is valid if its size is less than, or equal to, the value of this keyword. 798 * 799 * <p> 800 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 801 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 802 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 803 * 804 * <p> 805 * Only allowed for the following types: <js>"array"</js>. 806 * 807 * <h5 class='section'>Used for:</h5> 808 * <ul class='spaced-list'> 809 * <li> 810 * Server-side schema-based parsing validation. 811 * <li> 812 * Server-side generated Swagger documentation. 813 * <li> 814 * Client-side schema-based serializing validation. 815 * </ul> 816 */ 817 long maxItems() default -1; 818 819 /** 820 * Synonym for {@link #maxItems()}. 821 */ 822 long maxi() default -1; 823 824 /** 825 * <mk>minItems</mk> field of the {@doc ExtSwaggerParameterObject}. 826 * 827 * <p> 828 * An array or collection is valid if its size is greater than, or equal to, the value of this keyword. 829 * 830 * <p> 831 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 832 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 833 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 834 * 835 * <p> 836 * Only allowed for the following types: <js>"array"</js>. 837 * 838 * <h5 class='section'>Used for:</h5> 839 * <ul class='spaced-list'> 840 * <li> 841 * Server-side schema-based parsing validation. 842 * <li> 843 * Server-side generated Swagger documentation. 844 * <li> 845 * Client-side schema-based serializing validation. 846 * </ul> 847 */ 848 long minItems() default -1; 849 850 /** 851 * Synonym for {@link #minItems()}. 852 */ 853 long mini() default -1; 854 855 /** 856 * <mk>uniqueItems</mk> field of the {@doc ExtSwaggerParameterObject}. 857 * 858 * <p> 859 * If <jk>true</jk> the input validates successfully if all of its elements are unique. 860 * 861 * <p> 862 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 863 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 864 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 865 * 866 * <p> 867 * If the parameter type is a subclass of {@link Set}, this validation is skipped (since a set can only contain unique items anyway). 868 * <br>Otherwise, the collection or array is checked for duplicate items. 869 * 870 * <p> 871 * Only allowed for the following types: <js>"array"</js>. 872 * 873 * <h5 class='section'>Used for:</h5> 874 * <ul class='spaced-list'> 875 * <li> 876 * Server-side schema-based parsing validation. 877 * <li> 878 * Server-side generated Swagger documentation. 879 * <li> 880 * Client-side schema-based serializing validation. 881 * </ul> 882 */ 883 boolean uniqueItems() default false; 884 885 /** 886 * Synonym for {@link #uniqueItems()}. 887 */ 888 boolean ui() default false; 889 890 /** 891 * <mk>enum</mk> field of the {@doc ExtSwaggerParameterObject}. 892 * 893 * <p> 894 * If specified, the input validates successfully if it is equal to one of the elements in this array. 895 * 896 * <p> 897 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 898 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 899 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 900 * 901 * <p> 902 * The format is a {@doc SimplifiedJson} array or comma-delimited list. 903 * <br>Multiple lines are concatenated with newlines. 904 * 905 * <h5 class='section'>Examples:</h5> 906 * <p class='bcode w800'> 907 * <jc>// Comma-delimited list</jc> 908 * <jk>public</jk> Collection<Pet> findPetsByStatus( 909 * <ja>@Query</ja>( 910 * name=<js>"status"</js>, 911 * _enum=<js>"AVAILABLE,PENDING,SOLD"</js>, 912 * ) PetStatus status 913 * ) {...} 914 * </p> 915 * <p class='bcode w800'> 916 * <jc>// JSON array</jc> 917 * <jk>public</jk> Collection<Pet> findPetsByStatus( 918 * <ja>@Query</ja>( 919 * name=<js>"status"</js>, 920 * _enum=<js>"['AVAILABLE','PENDING','SOLD']"</js>, 921 * ) PetStatus status 922 * ) {...} 923 * </p> 924 * 925 * <h5 class='section'>Used for:</h5> 926 * <ul class='spaced-list'> 927 * <li> 928 * Server-side schema-based parsing validation. 929 * <li> 930 * Server-side generated Swagger documentation. 931 * <li> 932 * Client-side schema-based serializing validation. 933 * </ul> 934 */ 935 String[] _enum() default {}; 936 937 /** 938 * Synonym for {@link #_enum()}. 939 */ 940 String[] e() default {}; 941 942 /** 943 * <mk>multipleOf</mk> field of the {@doc ExtSwaggerParameterObject}. 944 * 945 * <p> 946 * A numeric instance is valid if the result of the division of the instance by this keyword's value is an integer. 947 * <br>The value must be a valid JSON number. 948 * 949 * <p> 950 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 951 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 952 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 953 * 954 * <p> 955 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 956 * 957 * <h5 class='section'>Used for:</h5> 958 * <ul class='spaced-list'> 959 * <li> 960 * Server-side schema-based parsing validation. 961 * <li> 962 * Server-side generated Swagger documentation. 963 * <li> 964 * Client-side schema-based serializing validation. 965 * </ul> 966 */ 967 String multipleOf() default ""; 968 969 /** 970 * Synonym for {@link #multipleOf()}. 971 */ 972 String mo() default ""; 973 974 //================================================================================================================= 975 // Other 976 //================================================================================================================= 977 978 /** 979 * A serialized example of the parameter. 980 * 981 * <p> 982 * This attribute defines a representation of the value that is used by <c>BasicRestInfoProvider</c> to construct 983 * an example of parameter. 984 * 985 * <h5 class='section'>Example:</h5> 986 * <p class='bcode w800'> 987 * <ja>@Query</ja>( 988 * name=<js>"status"</js>, 989 * type=<js>"array"</js>, 990 * collectionFormat=<js>"csv"</js>, 991 * example=<js>"AVAILABLE,PENDING"</js> 992 * ) 993 * PetStatus[] status 994 * </p> 995 * 996 * <p> 997 * If not specified, Juneau will automatically create examples from sample POJOs serialized using the registered {@link HttpPartSerializer}. 998 * <br> 999 * 1000 * </p> 1001 * <h5 class='section'>Used for:</h5> 1002 * <ul class='spaced-list'> 1003 * <li> 1004 * Server-side generated Swagger documentation. 1005 * </ul> 1006 * 1007 * <ul class='seealso'> 1008 * <li class='ja'>{@link Example} 1009 * <li class='jc'>{@link BeanContext} 1010 * <ul> 1011 * <li class='jf'>{@link BeanContext#BEAN_examples BEAN_examples} 1012 * </ul> 1013 * <li class='jc'>{@link JsonSchemaSerializer} 1014 * <ul> 1015 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_addExamplesTo JSONSCHEMA_addExamplesTo} 1016 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples JSONSCHEMA_allowNestedExamples} 1017 * </ul> 1018 * </ul> 1019 * 1020 * <ul class='notes'> 1021 * <li> 1022 * The format is a {@doc SimplifiedJson} object or plain text string. 1023 * <br>Multiple lines are concatenated with newlines. 1024 * <li> 1025 * Supports {@doc RestSvlVariables} 1026 * (e.g. <js>"$L{my.localized.variable}"</js>). 1027 * </ul> 1028 */ 1029 String[] example() default {}; 1030 1031 /** 1032 * Synonym for {@link #example()}. 1033 */ 1034 String[] ex() default {}; 1035 1036 /** 1037 * Free-form value for the {@doc ExtSwaggerParameterObject}. 1038 * 1039 * <p> 1040 * This is a {@doc SimplifiedJson} object that makes up the swagger information for this field. 1041 * 1042 * <p> 1043 * The following are completely equivalent ways of defining the swagger description of the Query object: 1044 * <p class='bcode w800'> 1045 * <jc>// Normal</jc> 1046 * <ja>@Query</ja>( 1047 * name=<js>"status"</js>, 1048 * description=<js>"Status values that need to be considered for filter."</js>, 1049 * required=<jk>true</jk>, 1050 * type=<js>"array"</js>, 1051 * items=<ja>@Items</ja>( 1052 * type=<js>"string"</js>, 1053 * _enum=<js>"AVAILABLE,PENDING,SOLD"</js>, 1054 * _default=<js>"AVAILABLE"</js> 1055 * ), 1056 * example=<js>"['AVAILABLE','PENDING']"</js> 1057 * ) 1058 * </p> 1059 * <p class='bcode w800'> 1060 * <jc>// Free-form</jc> 1061 * <ja>@Query</ja>( 1062 * name=<js>"status"</js>, 1063 * api={ 1064 * <js>"description: 'Status values that need to be considered for filter.',"</js>, 1065 * <js>"required: true,"</js>, 1066 * <js>"type: 'array',"</js>, 1067 * <js>"items: {"</js>, 1068 * <js>"type: 'string',"</js>, 1069 * <js>"enum: 'AVAILABLE,PENDING,SOLD',"</js>, 1070 * <js>"default: 'AVAILABLE'"</js>, 1071 * <js>"}"</js>, 1072 * <js>"example: "['AVAILABLE','PENDING']"</js> 1073 * } 1074 * ) 1075 * </p> 1076 * <p class='bcode w800'> 1077 * <jc>// Free-form using variables</jc> 1078 * <ja>@Query</ja>( 1079 * name=<js>"status"</js>, 1080 * api=<js>"$L{statusSwagger}"</js> 1081 * ) 1082 * </p> 1083 * <p class='bcode w800'> 1084 * <mc>// Contents of MyResource.properties</mc> 1085 * <mk>statusSwagger</mk> = <mv>{ description: "Status values that need to be considered for filter.", required: true, type: "array", items: {type: "string", enum: "AVAILABLE,PENDING,SOLD", default: "AVAILABLE"}, example: "['AVAILABLE','PENDING']" } }</mv> 1086 * </p> 1087 * 1088 * <p> 1089 * The reasons why you may want to use this field include: 1090 * <ul> 1091 * <li>You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file. 1092 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 1093 * </ul> 1094 * 1095 * <h5 class='section'>Used for:</h5> 1096 * <ul class='spaced-list'> 1097 * <li> 1098 * Server-side generated Swagger documentation. 1099 * </ul> 1100 * 1101 * <ul class='notes'> 1102 * <li> 1103 * Note that the only swagger field you can't specify using this value is <js>"name"</js> whose value needs to be known during servlet initialization. 1104 * <li> 1105 * Automatic validation is NOT performed on input based on attributes in this value. 1106 * <li> 1107 * The format is a {@doc SimplifiedJson} object. 1108 * <li> 1109 * The leading/trailing <c>{ }</c> characters are optional. 1110 * <br>The following two example are considered equivalent: 1111 * <p class='bcode w800'> 1112 * <ja>@Query</ja>(api=<js>"{description: 'ID of order to fetch'}"</js>) 1113 * </p> 1114 * <p class='bcode w800'> 1115 * <ja>@Query</ja>(api=<js>"description: 'ID of order to fetch''"</js>) 1116 * </p> 1117 * <li> 1118 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 1119 * <li> 1120 * Supports {@doc RestSvlVariables} 1121 * (e.g. <js>"$L{my.localized.variable}"</js>). 1122 * <li> 1123 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 1124 * </ul> 1125 */ 1126 String[] api() default {}; 1127}