1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.juneau.annotation;
18
19 import static java.lang.annotation.RetentionPolicy.*;
20
21 import java.lang.annotation.*;
22
23 import org.apache.juneau.oapi.*;
24
25 /**
26 * Swagger items annotation.
27 *
28 * <p>
29 * A limited subset of JSON-Schema's items object.
30 *
31 * <p>
32 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@Rest</ja>-annotated classes.
33 * <br>Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiSerializer} and parsed through {@link OpenApiParser}.
34 *
35 * <h5 class='section'>Examples:</h5>
36 * <p class='bjava'>
37 * <jc>// Items have a specific set of enumerated string values</jc>
38 * <ja>@Query</ja>(
39 * name=<js>"status"</js>,
40 * schema=<ja>@Schema</ja>(
41 * type=<js>"array"</js>,
42 * collectionFormat=<js>"csv"</js>,
43 * items=<ja>@Items</ja>(
44 * type=<js>"string"</js>,
45 * enum_=<js>"AVAILABLE,PENDING,SOLD"</js>,
46 * default_=<js>"AVAILABLE"</js>
47 * )
48 * )
49 * )
50 * </p>
51 * <p class='bjava'>
52 * <jc>// An array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive)</jc>
53 * <ja>@Query</ja>(
54 * name=<js>"status"</js>,
55 * schema=<ja>@Schema</ja>(
56 * type=<js>"array"</js>,
57 * collectionFormat=<js>"csv"</js>,
58 * items=<ja>@Items</ja>(
59 * type=<js>"array"</js>,
60 * items=<ja>@SubItems</ja>(
61 * type=<js>"integer"</js>,
62 * minimum=<js>"0"</js>,
63 * maximum=<js>"63"</js>
64 * )
65 * )
66 * )
67 * )
68 * </p>
69 *
70 * <h5 class='section'>See Also:</h5><ul>
71 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>
72 * <li class='link'><a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>
73
74 * </ul>
75 */
76 @Documented
77 @Retention(RUNTIME)
78 public @interface Items {
79
80 /**
81 * <mk>default</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>.
82 *
83 * <h5 class='section'>Notes:</h5><ul>
84 * <li class='note'>
85 * The format is a plain-text string.
86 * </ul>
87 *
88 * @return The annotation value.
89 */
90 String[] default_() default {};
91
92 /**
93 * <mk>enum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>.
94 *
95 * <h5 class='section'>Notes:</h5><ul>
96 * <li class='note'>
97 * Each entry is a possible value. Can also contain comma-delimited lists of values.
98 * </ul>
99 *
100 * @return The annotation value.
101 */
102 String[] enum_() default {};
103
104 /**
105 * <mk>$ref</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>.
106 *
107 * <h5 class='section'>Notes:</h5><ul>
108 * <li class='note'>
109 * The format is a plain-text string.
110 * </ul>
111 *
112 * @return The annotation value.
113 */
114 String $ref() default "";
115
116 /**
117 * Synonym for {@link #collectionFormat()}.
118 *
119 * @return The annotation value.
120 */
121 String cf() default "";
122
123 /**
124 * <mk>collectionFormat</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#itemsObject">Swagger Items Object</a>.
125 *
126 * <h5 class='section'>Notes:</h5><ul>
127 * <li class='note'>
128 * The format is a plain-text string.
129 * </ul>
130 *
131 * @return The annotation value.
132 */
133 String collectionFormat() default "";
134
135 /**
136 * Optional description for the exposed API.
137 *
138 * @return The annotation value.
139 * @since 9.2.0
140 */
141 String[] description() 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 }