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