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