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