org.apache.juneau.http.annotation.Schema 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.*;
import org.apache.juneau.oapi.*;
/**
* Swagger schema annotation.
*
*
* The Schema Object allows the definition of input and output data types.
* These types can be objects, but also primitives and arrays.
* This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.
* On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
*
*
* Used to populate the auto-generated Swagger documentation and UI for server-side @RestResource -annotated classes.
*
Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiSerializer} and parsed through {@link OpenApiParser}.
*
*
Examples:
*
* // A response object thats a hex-encoded string
* @Response (
* schema=@Schema (
* type="string" ,
* format="binary"
* )
* )
*
*
* // Free-form
* @Response (
* schema=@Schema ({
* "type:'string'," ,
* "format:'binary'"
* })
* )
*
*
* // A request body consisting of an array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive)
* @Body (
* schema=@Schema (
* items=@Items (
* type="array" ,
* items=@SubItems (
* type="integer" ,
* minimum="0" ,
* maximum="63"
* )
* )
* )
* )
*
*
* See Also:
*
* - {@doc juneau-rest-server.Swagger}
*
- {@doc SwaggerSchemaObject}
*
*/
@Documented
@Retention(RUNTIME)
public @interface Schema {
/**
* $ref field of the {@doc SwaggerSchemaObject}.
*
*
* A JSON reference to the schema definition.
*
*
Notes:
*
* -
* The format is a JSON Reference.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String $ref() default "";
/**
* format field of the {@doc SwaggerSchemaObject}.
*
* Examples:
*
* // Used on parameter
* @RestMethod (name=PUT )
* public void setAge(
* @Body (type="integer" , format="int32" ) String input
* ) {...}
*
*
* Notes:
*
* -
* The format is plain text.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@doc SwaggerDataTypeFormats}
*
*/
String format() default "";
/**
* title field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is plain text.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String title() default "";
/**
* description field of the {@doc SwaggerSchemaObject}.
*
*
* A brief description of the body. This could contain examples of use.
*
*
Examples:
*
* // Used on parameter
* @RestMethod (name=POST )
* public void addPet(
* @Body (description="Pet object to add to the store" ) Pet input
* ) {...}
*
*
* // Used on class
* @RestMethod (name=POST )
* public void addPet(Pet input) {...}
*
* @Body (description="Pet object to add to the store" )
* public class Pet {...}
*
*
* Notes:
*
* -
* The format is plain text.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] description() default {};
/**
* default field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is any {@doc juneau-marshall.JsonDetails.SimplifiedJson}.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] _default() default {};
/**
* multipleOf field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String multipleOf() default "";
/**
* maximum field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String maximum() default "";
/**
* exclusiveMaximum field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
boolean exclusiveMaximum() default false;
/**
* minimum field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String minimum() default "";
/**
* exclusiveMinimum field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
boolean exclusiveMinimum() default false;
/**
* maxLength field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long maxLength() default -1;
/**
* minLength field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long minLength() default -1;
/**
* pattern field of the {@doc SwaggerSchemaObject}.
*
* Example:
*
* @RestMethod (name=PUT )
* public void doPut(@Body (format="/\\w+\\.\\d+/" ) String input) {...}
*
*
* Notes:
*
* -
* The format is plain text.
*
-
* This string SHOULD be a valid regular expression.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String pattern() default "";
/**
* maxItems field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long maxItems() default -1;
/**
* minItems field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is numeric.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long minItems() default -1;
/**
* uniqueItems field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is boolean.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
boolean uniqueItems() default false;
/**
* maxProperties field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long maxProperties() default -1;
/**
* minProperties field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
long minProperties() default -1;
/**
* required field of the {@doc SwaggerSchemaObject}.
*
*
* Determines whether this parameter is mandatory.
*
The property MAY be included and its default value is false.
*
*
Examples:
*
* // Used on parameter
* @RestMethod (name=POST )
* public void addPet(
* @Body (required=true ) Pet input
* ) {...}
*
*
* // Used on class
* @RestMethod (name=POST )
* public void addPet(Pet input) {...}
*
* @Body (required=true )
* public class Pet {...}
*
*
* Notes:
*
* -
* The format is boolean.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
boolean required() default false;
/**
* enum field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} array or comma-delimited list.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] _enum() default {};
/**
* type field of the {@doc SwaggerSchemaObject}.
*
* Examples:
*
* // Used on parameter
* @RestMethod (name=POST )
* public void addPet(
* @Body (type="object" ) Pet input
* ) {...}
*
*
* // Used on class
* @RestMethod (name=POST )
* public void addPet(Pet input) {...}
*
* @Body (type="object" )
* public class Pet {...}
*
*
* Notes:
*
* -
* The format is plain text.
*
-
* The possible values are:
*
* "object"
* "string"
* "number"
* "integer"
* "boolean"
* "array"
* "file"
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*
* See Also:
*
* - {@doc SwaggerDataTypes}
*
*
*/
String type() default "";
/**
* items field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
Items items() default @Items;
/**
* collectionFormat field.
*
*
* Note that this field isn't part of the Swagger 2.0 specification, but the specification does not specify how
* items are supposed to be represented.
*
*
* Determines the format of the array if type "array" is used.
*
Can only be used if type is "array" .
*
*
Possible values are:
*
* -
*
"csv" (default) - Comma-separated values (e.g. "foo,bar" ).
* -
*
"ssv" - Space-separated values (e.g. "foo bar" ).
* -
*
"tsv" - Tab-separated values (e.g. "foo\tbar" ).
* -
*
"pipes - Pipe-separated values (e.g. "foo|bar" ).
* -
*
"multi" - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. "foo=bar&foo=baz" ).
* -
*
"uon" - UON notation (e.g. "@(foo,bar)" ).
*
*
*
* Static strings are defined in {@link CollectionFormatType}.
*
*
* Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.
*
*
Used for:
*
* -
* Server-side schema-based parsing.
*
-
* Server-side generated Swagger documentation.
*
-
* Client-side schema-based serializing.
*
*/
String collectionFormat() default "";
/**
* allOf field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] allOf() default {};
/**
* properties field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] properties() default {};
/**
* additionalProperties field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] additionalProperties() default {};
/**
* discriminator field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String discriminator() default "";
/**
* readOnly field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
boolean readOnly() default false;
/**
* xml field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] xml() default {};
/**
* externalDocs field of the {@doc SwaggerSchemaObject}.
*
* Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
ExternalDocs externalDocs() default @ExternalDocs;
/**
* example field of the {@doc SwaggerSchemaObject}.
*
*
* A free-form property to include an example of an instance for this schema.
*
*
* This attribute defines a JSON representation of the body value that is used by BasicRestInfoProvider to construct
* media-type-based examples of the body of the request.
*
*
Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object or plain text string.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] example() default {};
/**
* x-examples field of the {@doc SwaggerSchemaObject}.
*
*
* This is a JSON object whose keys are media types and values are string representations of that value.
*
*
Notes:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] examples() default {};
/**
* Specifies that schema information for this part should not be shown in the generated Swagger documentation.
*/
boolean ignore() default false;
/**
* Free-form value for the {@doc SwaggerSchemaObject}.
*
*
* This is a JSON object that makes up the swagger information for this field.
*
*
* The following are completely equivalent ways of defining the swagger description of a Schema object:
*
* // Normal
* @Schema (
* type="array" ,
* items=@Items (
* $ref="#/definitions/Pet"
* )
* )
*
*
* // Free-form
* @Schema (
* "type: 'array'," ,
* "items: {" ,
* "$ref: '#/definitions/Pet'" ,
* "}"
* )
*
*
* // Free-form using variables
* @Schema ("$L{petArraySwagger}" )
*
*
* // Contents of MyResource.properties
* petArraySwagger = { type: "array", items: { $ref: "#/definitions/Pet" } }
*
*
*
* 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:
*
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
-
* The leading/trailing
{ } characters are optional.
*
The following two example are considered equivalent:
*
* @Schema ("{type: 'array'}" )
*
*
* @Schema ("type: 'array'" )
*
* -
* 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 {};
}