001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.commons; 018 019import static java.lang.annotation.RetentionPolicy.*; 020 021import java.lang.annotation.*; 022 023/** 024 * Swagger items annotation. 025 * 026 * <p> 027 * A limited subset of JSON-Schema's items object. 028 * 029 * <p> 030 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@Rest</ja>-annotated classes. 031 * <br>Also used to define OpenAPI schema information for POJOs serialized through <c>OpenApiSerializer</c> and parsed through <c>OpenApiParser</c>. 032 * 033 * <h5 class='section'>Examples:</h5> 034 * <p class='bjava'> 035 * <jc>// Items have a specific set of enumerated string values</jc> 036 * <ja>@Query</ja>( 037 * name=<js>"status"</js>, 038 * schema=<ja>@Schema</ja>( 039 * type=<js>"array"</js>, 040 * collectionFormat=<js>"csv"</js>, 041 * items=<ja>@Items</ja>( 042 * type=<js>"string"</js>, 043 * enum_=<js>"AVAILABLE,PENDING,SOLD"</js>, 044 * default_=<js>"AVAILABLE"</js> 045 * ) 046 * ) 047 * ) 048 * </p> 049 * <p class='bjava'> 050 * <jc>// An array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive)</jc> 051 * <ja>@Query</ja>( 052 * name=<js>"status"</js>, 053 * schema=<ja>@Schema</ja>( 054 * type=<js>"array"</js>, 055 * collectionFormat=<js>"csv"</js>, 056 * items=<ja>@Items</ja>( 057 * type=<js>"array"</js>, 058 * items=<ja>@SubItems</ja>( 059 * type=<js>"integer"</js>, 060 * minimum=<js>"0"</js>, 061 * maximum=<js>"63"</js> 062 * ) 063 * ) 064 * ) 065 * ) 066 * </p> 067 * 068 * <h5 class='section'>See Also:</h5><ul> 069 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> 070 * <li class='link'><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a> 071 072 * </ul> 073 */ 074@Documented 075@Retention(RUNTIME) 076@SuppressWarnings({ 077 "java:S100" // Annotation methods use underscore suffix to avoid Java keyword conflicts (e.g., default_, enum_) 078}) 079public @interface Items { 080 081 /** 082 * <mk>default</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 083 * 084 * <h5 class='section'>Notes:</h5><ul> 085 * <li class='note'> 086 * The format is a plain-text string. 087 * </ul> 088 * 089 * @return The annotation value. 090 */ 091 String[] default_() default {}; 092 093 /** 094 * <mk>enum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 095 * 096 * <h5 class='section'>Notes:</h5><ul> 097 * <li class='note'> 098 * Each entry is a possible value. Can also contain comma-delimited lists of values. 099 * </ul> 100 * 101 * @return The annotation value. 102 */ 103 String[] enum_() default {}; 104 105 /** 106 * <mk>$ref</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 107 * 108 * <h5 class='section'>Notes:</h5><ul> 109 * <li class='note'> 110 * The format is a plain-text string. 111 * </ul> 112 * 113 * @return The annotation value. 114 */ 115 String $ref() default ""; 116 117 /** 118 * Synonym for {@link #collectionFormat()}. 119 * 120 * @return The annotation value. 121 */ 122 String cf() default ""; 123 124 /** 125 * <mk>collectionFormat</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 126 * 127 * <h5 class='section'>Notes:</h5><ul> 128 * <li class='note'> 129 * The format is a plain-text string. 130 * </ul> 131 * 132 * @return The annotation value. 133 */ 134 String collectionFormat() default ""; 135 136 /** 137 * Optional description for the exposed API. 138 * 139 * @return The annotation value. 140 * @since 9.2.0 141 */ 142 String[] description() default {}; 143 144 /** 145 * Synonym for {@link #default_()}. 146 * 147 * @return The annotation value. 148 */ 149 String[] df() default {}; 150 151 /** 152 * Synonym for {@link #enum_()}. 153 * 154 * @return The annotation value. 155 */ 156 String[] e() default {}; 157 158 /** 159 * Synonym for {@link #exclusiveMaximum()}. 160 * 161 * @return The annotation value. 162 */ 163 boolean emax() default false; 164 165 /** 166 * Synonym for {@link #exclusiveMinimum()}. 167 * 168 * @return The annotation value. 169 */ 170 boolean emin() default false; 171 172 /** 173 * <mk>exclusiveMaximum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 174 * 175 * <h5 class='section'>Notes:</h5><ul> 176 * <li class='note'> 177 * The format is a plain-text string. 178 * </ul> 179 * 180 * @return The annotation value. 181 */ 182 boolean exclusiveMaximum() default false; 183 184 /** 185 * <mk>exclusiveMinimum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 186 * 187 * <h5 class='section'>Notes:</h5><ul> 188 * <li class='note'> 189 * The format is a plain-text string. 190 * </ul> 191 * 192 * @return The annotation value. 193 */ 194 boolean exclusiveMinimum() default false; 195 196 /** 197 * Synonym for {@link #format()}. 198 * 199 * @return The annotation value. 200 */ 201 String f() default ""; 202 203 /** 204 * <mk>format</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 205 * 206 * <h5 class='section'>Notes:</h5><ul> 207 * <li class='note'> 208 * The format is a plain-text string. 209 * </ul> 210 * 211 * @return The annotation value. 212 */ 213 String format() default ""; 214 215 /** 216 * <mk>items</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 217 * 218 * <p> 219 * Describes the type of items in the array. 220 * 221 * @return The annotation value. 222 */ 223 SubItems items() default @SubItems; 224 225 /** 226 * Synonym for {@link #maximum()}. 227 * 228 * @return The annotation value. 229 */ 230 String max() default ""; 231 232 /** 233 * Synonym for {@link #maxItems()}. 234 * 235 * @return The annotation value. 236 */ 237 long maxi() default -1; 238 239 /** 240 * <mk>maximum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 241 * 242 * <h5 class='section'>Notes:</h5><ul> 243 * <li class='note'> 244 * The format is a plain-text string. 245 * </ul> 246 * 247 * @return The annotation value. 248 */ 249 String maximum() default ""; 250 251 /** 252 * <mk>maxItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 253 * 254 * <h5 class='section'>Notes:</h5><ul> 255 * <li class='note'> 256 * The format is a plain-text string. 257 * </ul> 258 * 259 * @return The annotation value. 260 */ 261 long maxItems() default -1; 262 263 /** 264 * Synonym for {@link #maxLength()}. 265 * 266 * @return The annotation value. 267 */ 268 long maxl() default -1; 269 270 /** 271 * <mk>maxLength</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 272 * 273 * <h5 class='section'>Notes:</h5><ul> 274 * <li class='note'> 275 * The format is a plain-text string. 276 * </ul> 277 * 278 * @return The annotation value. 279 */ 280 long maxLength() default -1; 281 282 /** 283 * Synonym for {@link #minimum()}. 284 * 285 * @return The annotation value. 286 */ 287 String min() default ""; 288 289 /** 290 * Synonym for {@link #minItems()}. 291 * 292 * @return The annotation value. 293 */ 294 long mini() default -1; 295 296 /** 297 * <mk>minimum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 298 * 299 * <h5 class='section'>Notes:</h5><ul> 300 * <li class='note'> 301 * The format is a plain-text string. 302 * </ul> 303 * 304 * @return The annotation value. 305 */ 306 String minimum() default ""; 307 308 /** 309 * <mk>minItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 310 * 311 * <h5 class='section'>Notes:</h5><ul> 312 * <li class='note'> 313 * The format is a plain-text string. 314 * </ul> 315 * 316 * @return The annotation value. 317 */ 318 long minItems() default -1; 319 320 /** 321 * Synonym for {@link #minLength()}. 322 * 323 * @return The annotation value. 324 */ 325 long minl() default -1; 326 327 /** 328 * <mk>minLength</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 329 * 330 * <h5 class='section'>Notes:</h5><ul> 331 * <li class='note'> 332 * The format is a plain-text string. 333 * </ul> 334 * 335 * @return The annotation value. 336 */ 337 long minLength() default -1; 338 339 /** 340 * Synonym for {@link #multipleOf()}. 341 * 342 * @return The annotation value. 343 */ 344 String mo() default ""; 345 346 /** 347 * <mk>multipleOf</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 348 * 349 * <h5 class='section'>Notes:</h5><ul> 350 * <li class='note'> 351 * The format is a plain-text string. 352 * </ul> 353 * 354 * @return The annotation value. 355 */ 356 String multipleOf() default ""; 357 358 /** 359 * Synonym for {@link #pattern()}. 360 * 361 * @return The annotation value. 362 */ 363 String p() default ""; 364 365 /** 366 * <mk>pattern</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 367 * 368 * <h5 class='section'>Notes:</h5><ul> 369 * <li class='note'> 370 * The format is a plain-text string. 371 * </ul> 372 * 373 * @return The annotation value. 374 */ 375 String pattern() default ""; 376 377 /** 378 * Synonym for {@link #type()}. 379 * 380 * @return The annotation value. 381 */ 382 String t() default ""; 383 384 /** 385 * <mk>type</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 386 * 387 * <h5 class='section'>Notes:</h5><ul> 388 * <li class='note'> 389 * The format is a plain-text string. 390 * </ul> 391 * 392 * @return The annotation value. 393 */ 394 String type() default ""; 395 396 /** 397 * Synonym for {@link #uniqueItems()}. 398 * 399 * @return The annotation value. 400 */ 401 boolean ui() default false; 402 403 /** 404 * <mk>uniqueItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>. 405 * 406 * <h5 class='section'>Notes:</h5><ul> 407 * <li class='note'> 408 * The format is a plain-text string. 409 * </ul> 410 * 411 * @return The annotation value. 412 */ 413 boolean uniqueItems() default false; 414}