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