org.apache.juneau.http.annotation.SubItems Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.http.annotation;
import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
* Swagger items annotation.
*
*
* This class is essentially identical to {@link Items} except it's used for defining items of items.
*
*
* Since annotations cannot be nested, we're forced to create a separate annotation for it.
*
If you want to nest items further, you have to define them free-form using {@link #items()} as free-form JSON.
*
*
See Also:
*
* - {@doc juneau-rest-server.Swagger}
*
- {@doc SwaggerItemsObject}
*
*/
@Documented
@Retention(RUNTIME)
public @interface SubItems {
/**
* type field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String type() default "";
/**
* format field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String format() default "";
/**
* collectionFormat field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String collectionFormat() default "";
/**
* pattern field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String pattern() default "";
/**
* maximum field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String maximum() default "";
/**
* minimum field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String minimum() default "";
/**
* multipleOf field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String multipleOf() default "";
/**
* maxLength field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long maxLength() default -1;
/**
* minLength field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long minLength() default -1;
/**
* maxItems field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long maxItems() default -1;
/**
* minItems field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long minItems() default -1;
/**
* exclusiveMaximum field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
boolean exclusiveMaximum() default false;
/**
* exclusiveMinimum field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
boolean exclusiveMinimum() default false;
/**
* uniqueItems field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
boolean uniqueItems() default false;
/**
* default field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] _default() default {};
/**
* enum field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] _enum() default {};
/**
* $ref field of the {@doc SwaggerItemsObject}.
*
* Notes:
*
* -
* The format is a plain-text string.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String $ref() default "";
/**
* items field of the {@doc SwaggerItemsObject}.
*
*
* Describes the type of items in the array.
*
*
* This is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
It must be declared free-form because it's not possible to nest annotations in Java.
*/
String[] items() default {};
/**
* Free-form value for the {@doc SwaggerItemsObject}.
*
*
* This is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object that makes up the swagger information for this field.
*
*
* The following are completely equivalent ways of defining the swagger description of an Items object:
*
* // Normal
* @Query (
* name="status" ,
* type="array" ,
* items=@Items (
* type="string" ,
* _enum="AVAILABLE,PENDING,SOLD" ,
* _default="AVAILABLE"
* )
* )
*
*
* // Free-form
* @Query (
* name="status" ,
* type="array" ,
* items=@Items ({
* "type: 'string'" ,
* "enum: ['AVAILABLE','PENDING','SOLD']," ,
* "default: 'AVAILABLE'"
* })
* )
*
*
* // Free-form as part of parent
* @Query (
* name="status" ,
* api={
* "type:'array'," ,
* "items: {" ,
* "type: 'string'," ,
* "enum: ['AVAILABLE','PENDING','SOLD']," ,
* "default: 'AVAILABLE'" ,
* "}" )
* }
* )
*
*
* // Free-form with variables
* @Query (
* name="status" ,
* type="array" ,
* items=@Items ("$L{statusItemsSwagger}" )
* )
*
*
* // Contents of MyResource.properties
* statusItemsSwagger = { type: "string", enum: ["AVAILABLE","PENDING","SOLD"], default: "AVAILABLE" }
*
*
*
* The reasons why you may want to use this field include:
*
* - You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file.
*
- You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification.
*
*
* Notes:
*
* -
* Note that the only swagger field you can't specify using this value is
"name" whose value needs to be known during servlet initialization.
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
-
* The leading/trailing
{ } characters are optional.
*
The following two example are considered equivalent:
*
* @Items (api="{type: 'string'}" )
*
*
* @Items (api="type: 'string'" )
*
* -
* Multiple lines are concatenated with newlines so that you can format the value to be readable.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.
*
*/
String[] value() default {};
}