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