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