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.jsonschema.annotation; 014 015import static java.lang.annotation.RetentionPolicy.*; 016 017import java.lang.annotation.*; 018 019import org.apache.juneau.oapi.*; 020 021/** 022 * Swagger items annotation. 023 * 024 * <p> 025 * A limited subset of JSON-Schema's items object. 026 * 027 * <p> 028 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@Rest</ja>-annotated classes. 029 * <br>Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiSerializer} and parsed through {@link OpenApiParser}. 030 * 031 * <h5 class='section'>Examples:</h5> 032 * <p class='bcode w800'> 033 * <jc>// Items have a specific set of enumerated string values</jc> 034 * <ja>@Query</ja>( 035 * name=<js>"status"</js>, 036 * type=<js>"array"</js>, 037 * collectionFormat=<js>"csv"</js>, 038 * items=<ja>@Items</ja>( 039 * type=<js>"string"</js>, 040 * _enum=<js>"AVAILABLE,PENDING,SOLD"</js>, 041 * _default=<js>"AVAILABLE"</js> 042 * ) 043 * ) 044 * </p> 045 * <p class='bcode w800'> 046 * <jc>// Same but defined free-form</jc> 047 * <ja>@Query</ja>( 048 * name=<js>"status"</js>, 049 * type=<js>"array"</js>, 050 * collectionFormat=<js>"csv"</js>, 051 * items=<ja>@Items</ja>({ 052 * <js>"type:'string',"</js>, 053 * <js>"enum:'AVAILABLE,PENDING,SOLD',"</js>, 054 * <js>"default:'AVAILABLE'"</js> 055 * }) 056 * ) 057 * </p> 058 * <p class='bcode w800'> 059 * <jc>// An array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive)</jc> 060 * <ja>@Query</ja>( 061 * name=<js>"status"</js>, 062 * type=<js>"array"</js>, 063 * collectionFormat=<js>"csv"</js>, 064 * items=<ja>@Items</ja>( 065 * type=<js>"array"</js>, 066 * items=<ja>@SubItems</ja>( 067 * type=<js>"integer"</js>, 068 * minimum=<js>"0"</js>, 069 * maximum=<js>"63"</js> 070 * ) 071 * ) 072 * ) 073 * </p> 074 * 075 * <ul class='seealso'> 076 * <li class='link'>{@doc RestSwagger} 077 * <li class='extlink'>{@doc ExtSwaggerItemsObject} 078 * </ul> 079 */ 080@Documented 081@Retention(RUNTIME) 082public @interface Items { 083 084 /** 085 * <mk>type</mk> field of the {@doc ExtSwaggerItemsObject}. 086 * 087 * <ul class='notes'> 088 * <li> 089 * The format is a plain-text string. 090 * <li> 091 * Supports {@doc RestSvlVariables} 092 * (e.g. <js>"$L{my.localized.variable}"</js>). 093 * </ul> 094 */ 095 String type() default ""; 096 097 /** 098 * Synonym for {@link #type()}. 099 */ 100 String t() default ""; 101 102 /** 103 * <mk>format</mk> field of the {@doc ExtSwaggerItemsObject}. 104 * 105 * <ul class='notes'> 106 * <li> 107 * The format is a plain-text string. 108 * <li> 109 * Supports {@doc RestSvlVariables} 110 * (e.g. <js>"$L{my.localized.variable}"</js>). 111 * </ul> 112 */ 113 String format() default ""; 114 115 /** 116 * Synonym for {@link #format()}. 117 */ 118 String f() default ""; 119 120 /** 121 * <mk>collectionFormat</mk> field of the {@doc ExtSwaggerItemsObject}. 122 * 123 * <ul class='notes'> 124 * <li> 125 * The format is a plain-text string. 126 * <li> 127 * Supports {@doc RestSvlVariables} 128 * (e.g. <js>"$L{my.localized.variable}"</js>). 129 * </ul> 130 */ 131 String collectionFormat() default ""; 132 133 /** 134 * Synonym for {@link #collectionFormat()}. 135 */ 136 String cf() default ""; 137 138 /** 139 * <mk>pattern</mk> field of the {@doc ExtSwaggerItemsObject}. 140 * 141 * <ul class='notes'> 142 * <li> 143 * The format is a plain-text string. 144 * <li> 145 * Supports {@doc RestSvlVariables} 146 * (e.g. <js>"$L{my.localized.variable}"</js>). 147 * </ul> 148 */ 149 String pattern() default ""; 150 151 /** 152 * Synonym for {@link #pattern()}. 153 */ 154 String p() default ""; 155 156 /** 157 * <mk>maximum</mk> field of the {@doc ExtSwaggerItemsObject}. 158 * 159 * <ul class='notes'> 160 * <li> 161 * The format is a plain-text string. 162 * <li> 163 * Supports {@doc RestSvlVariables} 164 * (e.g. <js>"$L{my.localized.variable}"</js>). 165 * </ul> 166 */ 167 String maximum() default ""; 168 169 /** 170 * Synonym for {@link #maximum()}. 171 */ 172 String max() default ""; 173 174 /** 175 * <mk>minimum</mk> field of the {@doc ExtSwaggerItemsObject}. 176 * 177 * <ul class='notes'> 178 * <li> 179 * The format is a plain-text string. 180 * <li> 181 * Supports {@doc RestSvlVariables} 182 * (e.g. <js>"$L{my.localized.variable}"</js>). 183 * </ul> 184 */ 185 String minimum() default ""; 186 187 /** 188 * Synonym for {@link #minimum()}. 189 */ 190 String min() default ""; 191 192 /** 193 * <mk>multipleOf</mk> field of the {@doc ExtSwaggerItemsObject}. 194 * 195 * <ul class='notes'> 196 * <li> 197 * The format is a plain-text string. 198 * <li> 199 * Supports {@doc RestSvlVariables} 200 * (e.g. <js>"$L{my.localized.variable}"</js>). 201 * </ul> 202 */ 203 String multipleOf() default ""; 204 205 /** 206 * Synonym for {@link #multipleOf()}. 207 */ 208 String mo() default ""; 209 210 /** 211 * <mk>maxLength</mk> field of the {@doc ExtSwaggerItemsObject}. 212 * 213 * <ul class='notes'> 214 * <li> 215 * The format is a plain-text string. 216 * <li> 217 * Supports {@doc RestSvlVariables} 218 * (e.g. <js>"$L{my.localized.variable}"</js>). 219 * </ul> 220 */ 221 long maxLength() default -1; 222 223 /** 224 * Synonym for {@link #maxLength()}. 225 */ 226 long maxl() default -1; 227 228 /** 229 * <mk>minLength</mk> field of the {@doc ExtSwaggerItemsObject}. 230 * 231 * <ul class='notes'> 232 * <li> 233 * The format is a plain-text string. 234 * <li> 235 * Supports {@doc RestSvlVariables} 236 * (e.g. <js>"$L{my.localized.variable}"</js>). 237 * </ul> 238 */ 239 long minLength() default -1; 240 241 /** 242 * Synonym for {@link #minLength()}. 243 */ 244 long minl() default -1; 245 246 /** 247 * <mk>maxItems</mk> field of the {@doc ExtSwaggerItemsObject}. 248 * 249 * <ul class='notes'> 250 * <li> 251 * The format is a plain-text string. 252 * <li> 253 * Supports {@doc RestSvlVariables} 254 * (e.g. <js>"$L{my.localized.variable}"</js>). 255 * </ul> 256 */ 257 long maxItems() default -1; 258 259 /** 260 * Synonym for {@link #maxItems()}. 261 */ 262 long maxi() default -1; 263 264 /** 265 * <mk>minItems</mk> field of the {@doc ExtSwaggerItemsObject}. 266 * 267 * <ul class='notes'> 268 * <li> 269 * The format is a plain-text string. 270 * <li> 271 * Supports {@doc RestSvlVariables} 272 * (e.g. <js>"$L{my.localized.variable}"</js>). 273 * </ul> 274 */ 275 long minItems() default -1; 276 277 /** 278 * Synonym for {@link #minItems()}. 279 */ 280 long mini() default -1; 281 282 /** 283 * <mk>exclusiveMaximum</mk> field of the {@doc ExtSwaggerItemsObject}. 284 * 285 * <ul class='notes'> 286 * <li> 287 * The format is a plain-text string. 288 * <li> 289 * Supports {@doc RestSvlVariables} 290 * (e.g. <js>"$L{my.localized.variable}"</js>). 291 * </ul> 292 */ 293 boolean exclusiveMaximum() default false; 294 295 /** 296 * Synonym for {@link #exclusiveMaximum()}. 297 */ 298 boolean emax() default false; 299 300 /** 301 * <mk>exclusiveMinimum</mk> field of the {@doc ExtSwaggerItemsObject}. 302 * 303 * <ul class='notes'> 304 * <li> 305 * The format is a plain-text string. 306 * <li> 307 * Supports {@doc RestSvlVariables} 308 * (e.g. <js>"$L{my.localized.variable}"</js>). 309 * </ul> 310 */ 311 boolean exclusiveMinimum() default false; 312 313 /** 314 * Synonym for {@link #exclusiveMinimum()}. 315 */ 316 boolean emin() default false; 317 318 /** 319 * <mk>uniqueItems</mk> field of the {@doc ExtSwaggerItemsObject}. 320 * 321 * <ul class='notes'> 322 * <li> 323 * The format is a plain-text string. 324 * <li> 325 * Supports {@doc RestSvlVariables} 326 * (e.g. <js>"$L{my.localized.variable}"</js>). 327 * </ul> 328 */ 329 boolean uniqueItems() default false; 330 331 /** 332 * Synonym for {@link #uniqueItems()}. 333 */ 334 boolean ui() default false; 335 336 /** 337 * <mk>default</mk> field of the {@doc ExtSwaggerItemsObject}. 338 * 339 * <ul class='notes'> 340 * <li> 341 * The format is a plain-text string. 342 * <li> 343 * Supports {@doc RestSvlVariables} 344 * (e.g. <js>"$L{my.localized.variable}"</js>). 345 * </ul> 346 */ 347 String[] _default() default {}; 348 349 /** 350 * Synonym for {@link #_default()}. 351 */ 352 String[] df() default {}; 353 354 /** 355 * <mk>enum</mk> field of the {@doc ExtSwaggerItemsObject}. 356 * 357 * <ul class='notes'> 358 * <li> 359 * The format is a plain-text string. 360 * <li> 361 * Supports {@doc RestSvlVariables} 362 * (e.g. <js>"$L{my.localized.variable}"</js>). 363 * </ul> 364 */ 365 String[] _enum() default {}; 366 367 /** 368 * Synonym for {@link #_enum()}. 369 */ 370 String[] e() default {}; 371 372 /** 373 * <mk>$ref</mk> field of the {@doc ExtSwaggerItemsObject}. 374 * 375 * <ul class='notes'> 376 * <li> 377 * The format is a plain-text string. 378 * <li> 379 * Supports {@doc RestSvlVariables} 380 * (e.g. <js>"$L{my.localized.variable}"</js>). 381 * </ul> 382 */ 383 String $ref() default ""; 384 385 /** 386 * <mk>items</mk> field of the {@doc ExtSwaggerItemsObject}. 387 * 388 * <p> 389 * Describes the type of items in the array. 390 */ 391 SubItems items() default @SubItems; 392 393 /** 394 * Free-form value for the {@doc ExtSwaggerItemsObject}. 395 * 396 * <p> 397 * This is a {@doc SimplifiedJson} object that makes up the swagger information for this field. 398 * 399 * <p> 400 * The following are completely equivalent ways of defining the swagger description of an Items object: 401 * <p class='bcode w800'> 402 * <jc>// Normal</jc> 403 * <ja>@Query</ja>( 404 * name=<js>"status"</js>, 405 * type=<js>"array"</js>, 406 * items=<ja>@Items</ja>( 407 * type=<js>"string"</js>, 408 * _enum=<js>"AVAILABLE,PENDING,SOLD"</js>, 409 * _default=<js>"AVAILABLE"</js> 410 * ) 411 * ) 412 * </p> 413 * <p class='bcode w800'> 414 * <jc>// Free-form</jc> 415 * <ja>@Query</ja>( 416 * name=<js>"status"</js>, 417 * type=<js>"array"</js>, 418 * items=<ja>@Items</ja>({ 419 * <js>"type: 'string'"</js>, 420 * <js>"enum: ['AVAILABLE','PENDING','SOLD'],"</js>, 421 * <js>"default: 'AVAILABLE'"</js> 422 * }) 423 * ) 424 * </p> 425 * <p class='bcode w800'> 426 * <jc>// Free-form as part of parent</jc> 427 * <ja>@Query</ja>( 428 * name=<js>"status"</js>, 429 * api={ 430 * <js>"type:'array',"</js>, 431 * <js>"items: {"</js>, 432 * <js>"type: 'string',"</js>, 433 * <js>"enum: ['AVAILABLE','PENDING','SOLD'],"</js>, 434 * <js>"default: 'AVAILABLE'"</js>, 435 * <js>"}"</js>) 436 * } 437 * ) 438 * </p> 439 * <p class='bcode w800'> 440 * <jc>// Free-form with variables</jc> 441 * <ja>@Query</ja>( 442 * name=<js>"status"</js>, 443 * type=<js>"array"</js>, 444 * items=<ja>@Items</ja>(<js>"$L{statusItemsSwagger}"</js>) 445 * ) 446 * </p> 447 * <p class='bcode w800'> 448 * <mc>// Contents of MyResource.properties</mc> 449 * <mk>statusItemsSwagger</mk> = <mv>{ type: "string", enum: ["AVAILABLE","PENDING","SOLD"], default: "AVAILABLE" }</mv> 450 * </p> 451 * 452 * <p> 453 * The reasons why you may want to use this field include: 454 * <ul> 455 * <li>You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file. 456 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 457 * </ul> 458 * 459 * <ul class='notes'> 460 * <li> 461 * 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. 462 * <li> 463 * The format is a {@doc SimplifiedJson} object. 464 * <li> 465 * The leading/trailing <c>{ }</c> characters are optional. 466 * <br>The following two example are considered equivalent: 467 * <p class='bcode w800'> 468 * <ja>@Items</ja>(api=<js>"{type: 'string'}"</js>) 469 * </p> 470 * <p class='bcode w800'> 471 * <ja>@Items</ja>(api=<js>"type: 'string'"</js>) 472 * </p> 473 * <li> 474 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 475 * <li> 476 * Supports {@doc RestSvlVariables} 477 * (e.g. <js>"$L{my.localized.variable}"</js>). 478 * <li> 479 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 480 * </ul> 481 */ 482 String[] value() default {}; 483}