io.swagger.v3.oas.annotations.media

Annotation Type Schema

@Target(value={FIELD,METHOD,PARAMETER,TYPE,ANNOTATION_TYPE})
 @Retention(value=RUNTIME)
 @Inherited
public @interface Schema

The annotation may be used to define a Schema for a set of elements of the OpenAPI spec, and/or to define additional properties for the schema. It is applicable e.g. to parameters, schema classes (aka "models"), properties of such models, request and response content, header.

swagger-core resolver and swagger-jaxrs2 reader engine consider this annotation along with JAX-RS annotations, element type and context as input to resolve the annotated element into an OpenAPI schema definition for such element.

The annotation may be used also to override partly (e.g. the name) or fully (e.g providing a completely different representation) the schema of an element; for example if a specific class is provided as value of implementation(), it will override the element type

The annotation ArraySchema shall be used for array elements; ArraySchema and Schema cannot coexist

See Also:

Schema (OpenAPI specification), ArraySchema

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Schema.AccessMode	accessMode Allows to specify the access mode (AccessMode.READ_ONLY, READ_WRITE) AccessMode.READ_ONLY: value will not be written to during a request but may be returned during a response.
Class<?>[]	allOf Provides an array of java class implementations which can be used to describe multiple acceptable schemas.
String[]	allowableValues Provides a list of allowable values.
Class<?>[]	anyOf Provides an array of java class implementations which can be used to describe multiple acceptable schemas.
String	defaultValue Provides a default value.
boolean	deprecated Specifies that a schema is deprecated and should be transitioned out of usage.
String	description A description of the schema.
DiscriminatorMapping[]	discriminatorMapping Provides discriminator mapping values.
String	discriminatorProperty Provides a discriminator property value.
boolean	enumAsRef Allows enums to be resolved as a reference to a scheme added to components section.
String	example Provides an example of the schema.
boolean	exclusiveMaximum if true, makes the maximum value exclusive, or a less-than criteria.
boolean	exclusiveMinimum If true, makes the minimum value exclusive, or a greater-than criteria.
Extension[]	extensions The list of optional extensions
ExternalDocumentation	externalDocs Additional external documentation for this schema.
String	format Provides an optional override for the format.
boolean	hidden Allows schema to be marked as hidden.
Class<?>	implementation Provides a java class as implementation for this schema.
String	maximum Sets the maximum numeric value for a property.
int	maxLength Sets the maximum length of a string value.
int	maxProperties Constrains the number of arbitrary properties when additionalProperties is defined.
String	minimum Sets the minimum numeric value for a property.
int	minLength Sets the minimum length of a string value.
int	minProperties Constrains the number of arbitrary properties when additionalProperties is defined.
double	multipleOf Constrains a value such that when divided by the multipleOf, the remainder must be an integer.
String	name The name of the schema or property.
Class<?>	not Provides a java class to be used to disallow matching properties.
boolean	nullable If true, designates a value as possibly null.
Class<?>[]	oneOf Provides an array of java class implementations which can be used to describe multiple acceptable schemas.
String	pattern A pattern that the value must satisfy.
boolean	readOnly Deprecated. As of 2.0.0, replaced by accessMode()
String	ref References a schema definition in an external OpenAPI document.
boolean	required Mandates that the annotated item is required or not.
String[]	requiredProperties Allows multiple properties in an object to be marked as required.
Class<?>[]	subTypes An array of the sub types inheriting from this model.
String	title A title to explain the purpose of the schema.
String	type Provides an override for the basic type of the schema.
boolean	writeOnly Deprecated. As of 2.0.0, replaced by accessMode()

Element Detail

implementation

public abstract Class<?> implementation

Provides a java class as implementation for this schema. When provided, additional information in the Schema annotation (except for type information) will augment the java class after introspection.

Returns:

a class that implements this schema

Default:

java.lang.Void.class

not

public abstract Class<?> not

Provides a java class to be used to disallow matching properties.

Returns:

a class with disallowed properties

Default:

java.lang.Void.class

oneOf

public abstract Class<?>[] oneOf

Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If more than one match the derived schemas, a validation error will occur.

Returns:

the list of possible classes for a single match

Default:

{}

anyOf

public abstract Class<?>[] anyOf

Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If any match, the schema will be considered valid.

Returns:

the list of possible class matches

Default:

{}

allOf

public abstract Class<?>[] allOf

Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If all match, the schema will be considered valid

Returns:

the list of classes to match

Default:

{}

name

public abstract String name

The name of the schema or property.

Returns:

the name of the schema

Default:

""

title

public abstract String title

A title to explain the purpose of the schema.

Returns:

the title of the schema

Default:

""

multipleOf

public abstract double multipleOf

Constrains a value such that when divided by the multipleOf, the remainder must be an integer. Ignored if the value is 0.

Returns:

the multiplier constraint of the schema

Default:

0.0

maximum

public abstract String maximum

Sets the maximum numeric value for a property. Ignored if the value is an empty string.

Returns:

the maximum value for this schema

Default:

""

exclusiveMaximum

public abstract boolean exclusiveMaximum

if true, makes the maximum value exclusive, or a less-than criteria.

Returns:

the exclusive maximum value for this schema

Default:

false

minimum

public abstract String minimum

Sets the minimum numeric value for a property. Ignored if the value is an empty string or not a number.

Returns:

the minimum value for this schema

Default:

""

exclusiveMinimum

public abstract boolean exclusiveMinimum

If true, makes the minimum value exclusive, or a greater-than criteria.

Returns:

the exclusive minimum value for this schema

Default:

false

maxLength

public abstract int maxLength

Sets the maximum length of a string value. Ignored if the value is negative.

Returns:

the maximum length of this schema

Default:

2147483647

minLength

public abstract int minLength

Sets the minimum length of a string value. Ignored if the value is negative.

Returns:

the minimum length of this schema

Default:

0

pattern

public abstract String pattern

A pattern that the value must satisfy. Ignored if the value is an empty string.

Returns:

the pattern of this schema

Default:

""

maxProperties

public abstract int maxProperties

Constrains the number of arbitrary properties when additionalProperties is defined. Ignored if value is 0.

Returns:

the maximum number of properties for this schema

Default:

0

minProperties

public abstract int minProperties

Constrains the number of arbitrary properties when additionalProperties is defined. Ignored if value is 0.

Returns:

the minimum number of properties for this schema

Default:

0

requiredProperties

public abstract String[] requiredProperties

Allows multiple properties in an object to be marked as required.

Returns:

the list of required schema properties

Default:

{}

required

public abstract boolean required

Mandates that the annotated item is required or not.

Returns:

whether or not this schema is required

Default:

false

description

public abstract String description

A description of the schema.

Returns:

the schema's description

Default:

""

format

public abstract String format

Provides an optional override for the format. If a consumer is unaware of the meaning of the format, they shall fall back to using the basic type without format. For example, if \"type: integer, format: int128\" were used to designate a very large integer, most consumers will not understand how to handle it, and fall back to simply \"type: integer\"

Returns:

the schema's format

Default:

""

ref

public abstract String ref

References a schema definition in an external OpenAPI document.

Returns:

a reference to this schema

Default:

""

nullable

public abstract boolean nullable

If true, designates a value as possibly null.

Returns:

whether or not this schema is nullable

Default:

false

readOnly

@Deprecated
public abstract boolean readOnly

Deprecated. As of 2.0.0, replaced by accessMode()

Sets whether the value should only be read during a response but not read to during a request.

Returns:

whether or not this schema is read only

Default:

false

writeOnly

@Deprecated
public abstract boolean writeOnly

Deprecated. As of 2.0.0, replaced by accessMode()

Sets whether a value should only be written to during a request but not returned during a response.

Returns:

whether or not this schema is write only

Default:

false

accessMode

public abstract Schema.AccessMode accessMode

Allows to specify the access mode (AccessMode.READ_ONLY, READ_WRITE) AccessMode.READ_ONLY: value will not be written to during a request but may be returned during a response. AccessMode.WRITE_ONLY: value will only be written to during a request but not returned during a response. AccessMode.READ_WRITE: value will be written to during a request and returned during a response.

Returns:

the accessMode for this schema (property)

Default:

io.swagger.v3.oas.annotations.media.Schema.AccessMode.AUTO

example

public abstract String example

Provides an example of the schema. When associated with a specific media type, the example string shall be parsed by the consumer to be treated as an object or an array.

Returns:

an example of this schema

Default:

""

externalDocs

public abstract ExternalDocumentation externalDocs

Additional external documentation for this schema.

Returns:

additional schema documentation

Default:

@io.swagger.v3.oas.annotations.ExternalDocumentation

deprecated

public abstract boolean deprecated

Specifies that a schema is deprecated and should be transitioned out of usage.

Returns:

whether or not this schema is deprecated

Default:

false

type

public abstract String type

Provides an override for the basic type of the schema. Must be a valid type per the OpenAPI Specification.

Returns:

the type of this schema

Default:

""

allowableValues

public abstract String[] allowableValues

Provides a list of allowable values. This field map to the enum property in the OAS schema.

Returns:

a list of allowed schema values

Default:

{}

defaultValue

public abstract String defaultValue

Provides a default value.

Returns:

the default value of this schema

Default:

""

discriminatorProperty

public abstract String discriminatorProperty

Provides a discriminator property value.

Returns:

the discriminator property

Default:

""

discriminatorMapping

public abstract DiscriminatorMapping[] discriminatorMapping

Provides discriminator mapping values.

Returns:

the discriminator mappings

Default:

{}

hidden

public abstract boolean hidden

Allows schema to be marked as hidden.

Returns:

whether or not this schema is hidden

Default:

false

enumAsRef

public abstract boolean enumAsRef

Allows enums to be resolved as a reference to a scheme added to components section.

Returns:

whether or not this must be resolved as a reference

Since:

2.1.0

Default:

false

subTypes

public abstract Class<?>[] subTypes

An array of the sub types inheriting from this model.

Default:

{}

extensions

public abstract Extension[] extensions

The list of optional extensions

Returns:

an optional array of extensions

Default:

{}