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