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