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