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