Documentation

Schema extends AbstractAnnotation
in package

The openapi annotation base class.

Tags
Annotation

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 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.

A "Schema Object": https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject JSON Schema: http://json-schema.org/

Table of Contents

$_blacklist  : array<string|int, mixed>
List of properties are blacklisted from the JSON output.
$_context  : Context
$_nested  : array<string|int, mixed>
Declarative mapping of Annotation types to properties.
$_parents  : array<string|int, string>
Reverse mapping of $_nested with the allowed parent annotations.
$_required  : array<string|int, mixed>
The properties which are required by [the spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).
$_types  : array<string|int, mixed>
Specify the type of the property.
$_unmerged  : array<string|int, mixed>
Annotations that couldn't be merged by mapping or postprocessing.
$additionalItems  : mixed
http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.10.
$additionalProperties  : bool|object
http://json-schema.org/latest/json-schema-validation.html#anchor64.
$allOf  : array<string|int, Schema>
An instance validates successfully against this property if it validates successfully against all schemas defined by this property's value.
$anyOf  : array<string|int, Schema>
An instance validates successfully against this property if it validates successfully against at least one schema defined by this property's value.
$attachables  : mixed
Arbitrary attachables for this annotation.
$collectionFormat  : string
$const  : mixed
http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.24.
$contains  : mixed
http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.14.
$default  : mixed
Sets a default value to the parameter. The type of the value depends on the defined type. See http://json-schema.org/latest/json-schema-validation.html#anchor101.
$dependencies  : mixed
http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.21.
$deprecated  : bool
Specifies that a schema is deprecated and should be transitioned out of usage.
$description  : string
A description will provide explanation about the purpose of the instance described by this schema.
$discriminator  : Discriminator
Adds support for polymorphism.
$enum  : array<string|int, mixed>
See http://json-schema.org/latest/json-schema-validation.html#anchor76.
$example  : mixed
A free-form property to include an example of an instance for this schema.
$exclusiveMaximum  : bool
See http://json-schema.org/latest/json-schema-validation.html#anchor17.
$exclusiveMinimum  : bool
See http://json-schema.org/latest/json-schema-validation.html#anchor21.
$externalDocs  : ExternalDocumentation
Additional external documentation for this schema.
$format  : string
The extending format for the previously mentioned type. See Data Type Formats for further details.
$items  : Items
Required if type is "array". Describes the type of items in the array.
$maximum  : number
See http://json-schema.org/latest/json-schema-validation.html#anchor17.
$maxItems  : int
See http://json-schema.org/latest/json-schema-validation.html#anchor42.
$maxLength  : int
See http://json-schema.org/latest/json-schema-validation.html#anchor26.
$maxProperties  : int
An object instance is valid against "maxProperties" if its number of properties is less than, or equal to, the value of this property.
$minimum  : number
See http://json-schema.org/latest/json-schema-validation.html#anchor21.
$minItems  : int
See http://json-schema.org/latest/json-schema-validation.html#anchor45.
$minLength  : int
See http://json-schema.org/latest/json-schema-validation.html#anchor29.
$minProperties  : int
An object instance is valid against "minProperties" if its number of properties is greater than, or equal to, the value of this property.
$multipleOf  : number
A numeric instance is valid against "multipleOf" if the result of the division of the instance by this property's value is an integer.
$not  : mixed
http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.29.
$nullable  : bool
Allows sending a null value for the defined schema.
$oneOf  : array<string|int, Schema>
An instance validates successfully against this property if it validates successfully against exactly one schema defined by this property's value.
$pattern  : string
A string instance is considered valid if the regular expression matches the instance successfully.
$patternProperties  : mixed
http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.19.
$properties  : array<string|int, Property>
$propertyNames  : mixed
http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.22.
$readOnly  : bool
Relevant only for Schema "properties" definitions.
$ref  : string
$ref See https://swagger.io/docs/specification/using-ref/.
$required  : array<string|int, string>
An object instance is valid against this property if its property set contains all elements in this property's array value.
$schema  : string
The key into Components->schemas array.
$title  : string
Can be used to decorate a user interface with information about the data produced by this user interface. preferrably be short.
$type  : string
The type of the schema/property. The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".
$uniqueItems  : bool
See http://json-schema.org/latest/json-schema-validation.html#anchor49.
$writeOnly  : bool
Relevant only for Schema "properties" definitions.
$x  : array<string|int, mixed>
While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
$xml  : Xml
This may be used only on properties schemas.
__construct()  : mixed
__debugInfo()  : mixed
__get()  : mixed
__set()  : mixed
identity()  : string
Return a identity for easy debugging.
isRoot()  : bool
An annotation is a root if it is the top-level / outermost annotation in a PHP docblock.
jsonSerialize()  : mixed
Customize the way json_encode() renders the annotations.
matchNested()  : null|object
Find matching nested details.
merge()  : array<string|int, AbstractAnnotation>
Merge given annotations to their mapped properties configured in static::$_nested.
mergeProperties()  : void
Merge the properties from the given object into this annotation.
toJson()  : string
Generate the documentation in YAML format.
toYaml()  : string
Generate the documentation in YAML format.
validate()  : bool
Validate annotation tree, and log notices & warnings.
_identity()  : string
Helper for generating the identity().
_validate()  : bool
Recursively validate all annotation properties.
nested()  : AbstractAnnotation
Wrap the context with a reference to the annotation it is nested in.
validateArrayType()  : bool
Validate array type.
validateDefaultTypes()  : bool
Validates default Open Api types.
validateType()  : bool
Validates the matching of the property value to a annotation type.

Properties

$_blacklist

List of properties are blacklisted from the JSON output.

public static array<string|int, mixed> $_blacklist = ['_context', '_unmerged', 'attachables']

$_nested

Declarative mapping of Annotation types to properties.

public static array<string|int, mixed> $_nested = [\OpenApi\Annotations\Discriminator::class => 'discriminator', \OpenApi\Annotations\Items::class => 'items', \OpenApi\Annotations\Property::class => ['properties', 'property'], \OpenApi\Annotations\ExternalDocumentation::class => 'externalDocs', \OpenApi\Annotations\Xml::class => 'xml', \OpenApi\Annotations\AdditionalProperties::class => 'additionalProperties', \OpenApi\Annotations\Attachable::class => ['attachables']]
Tags
inheritdoc

$_parents

Reverse mapping of $_nested with the allowed parent annotations.

public static array<string|int, string> $_parents = [\OpenApi\Annotations\Components::class, \OpenApi\Annotations\Parameter::class, \OpenApi\Annotations\MediaType::class, \OpenApi\Annotations\Header::class]
Tags
inheritdoc

$_required

The properties which are required by [the spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).

public static array<string|int, mixed> $_required = []

$_types

Specify the type of the property.

public static array<string|int, mixed> $_types = ['description' => 'string', 'required' => '[string]', 'format' => 'string', 'collectionFormat' => ['csv', 'ssv', 'tsv', 'pipes', 'multi'], 'maximum' => 'number', 'exclusiveMaximum' => 'boolean', 'minimum' => 'number', 'exclusiveMinimum' => 'boolean', 'maxLength' => 'integer', 'minLength' => 'integer', 'pattern' => 'string', 'maxItems' => 'integer', 'minItems' => 'integer', 'uniqueItems' => 'boolean', 'multipleOf' => 'integer', 'allOf' => '[' . \OpenApi\Annotations\Schema::class . ']', 'oneOf' => '[' . \OpenApi\Annotations\Schema::class . ']', 'anyOf' => '[' . \OpenApi\Annotations\Schema::class . ']']
Tags
inheritdoc

$_unmerged

Annotations that couldn't be merged by mapping or postprocessing.

public array<string|int, mixed> $_unmerged = []

$additionalItems

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.10.

public mixed $additionalItems = \OpenApi\Generator::UNDEFINED

$additionalProperties

http://json-schema.org/latest/json-schema-validation.html#anchor64.

public bool|object $additionalProperties = \OpenApi\Generator::UNDEFINED

$allOf

An instance validates successfully against this property if it validates successfully against all schemas defined by this property's value.

public array<string|int, Schema> $allOf = \OpenApi\Generator::UNDEFINED

$anyOf

An instance validates successfully against this property if it validates successfully against at least one schema defined by this property's value.

public array<string|int, Schema> $anyOf = \OpenApi\Generator::UNDEFINED

$attachables

Arbitrary attachables for this annotation.

public mixed $attachables = \OpenApi\Generator::UNDEFINED

These will be ignored but can be used for custom processing.

$collectionFormat

public string $collectionFormat = \OpenApi\Generator::UNDEFINED

Determines the format of the array if type array is used. Possible values are: csv - comma separated values foo,bar. ssv - space separated values foo bar. tsv - tab separated values foo\tbar. pipes - pipe separated values foo|bar. multi - corresponds to multiple parameter instances instead of multiple values for a single instance foo=bar&foo=baz. This is valid only for parameters in "query" or "formData". Default value is csv.

$const

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.24.

public mixed $const = \OpenApi\Generator::UNDEFINED

$contains

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.14.

public mixed $contains = \OpenApi\Generator::UNDEFINED

$default

Sets a default value to the parameter. The type of the value depends on the defined type. See http://json-schema.org/latest/json-schema-validation.html#anchor101.

public mixed $default = \OpenApi\Generator::UNDEFINED

$dependencies

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.21.

public mixed $dependencies = \OpenApi\Generator::UNDEFINED

$deprecated

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

public bool $deprecated = \OpenApi\Generator::UNDEFINED

Default value is false.

$description

A description will provide explanation about the purpose of the instance described by this schema.

public string $description = \OpenApi\Generator::UNDEFINED

$discriminator

Adds support for polymorphism.

public Discriminator $discriminator = \OpenApi\Generator::UNDEFINED

The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See Composition and Inheritance for more details.

$enum

See http://json-schema.org/latest/json-schema-validation.html#anchor76.

public array<string|int, mixed> $enum = \OpenApi\Generator::UNDEFINED

$example

A free-form property to include an example of an instance for this schema.

public mixed $example = \OpenApi\Generator::UNDEFINED

To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.

$exclusiveMaximum

See http://json-schema.org/latest/json-schema-validation.html#anchor17.

public bool $exclusiveMaximum = \OpenApi\Generator::UNDEFINED

$exclusiveMinimum

See http://json-schema.org/latest/json-schema-validation.html#anchor21.

public bool $exclusiveMinimum = \OpenApi\Generator::UNDEFINED

$externalDocs

Additional external documentation for this schema.

public ExternalDocumentation $externalDocs = \OpenApi\Generator::UNDEFINED

$format

The extending format for the previously mentioned type. See Data Type Formats for further details.

public string $format = \OpenApi\Generator::UNDEFINED

$items

Required if type is "array". Describes the type of items in the array.

public Items $items = \OpenApi\Generator::UNDEFINED

$maximum

See http://json-schema.org/latest/json-schema-validation.html#anchor17.

public number $maximum = \OpenApi\Generator::UNDEFINED

$maxItems

See http://json-schema.org/latest/json-schema-validation.html#anchor42.

public int $maxItems = \OpenApi\Generator::UNDEFINED

$maxLength

See http://json-schema.org/latest/json-schema-validation.html#anchor26.

public int $maxLength = \OpenApi\Generator::UNDEFINED

$maxProperties

An object instance is valid against "maxProperties" if its number of properties is less than, or equal to, the value of this property.

public int $maxProperties = \OpenApi\Generator::UNDEFINED

$minimum

See http://json-schema.org/latest/json-schema-validation.html#anchor21.

public number $minimum = \OpenApi\Generator::UNDEFINED

$minItems

See http://json-schema.org/latest/json-schema-validation.html#anchor45.

public int $minItems = \OpenApi\Generator::UNDEFINED

$minLength

See http://json-schema.org/latest/json-schema-validation.html#anchor29.

public int $minLength = \OpenApi\Generator::UNDEFINED

$minProperties

An object instance is valid against "minProperties" if its number of properties is greater than, or equal to, the value of this property.

public int $minProperties = \OpenApi\Generator::UNDEFINED

$multipleOf

A numeric instance is valid against "multipleOf" if the result of the division of the instance by this property's value is an integer.

public number $multipleOf = \OpenApi\Generator::UNDEFINED

$not

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.29.

public mixed $not = \OpenApi\Generator::UNDEFINED

$nullable

Allows sending a null value for the defined schema.

public bool $nullable = \OpenApi\Generator::UNDEFINED

Default value is false.

$oneOf

An instance validates successfully against this property if it validates successfully against exactly one schema defined by this property's value.

public array<string|int, Schema> $oneOf = \OpenApi\Generator::UNDEFINED

$pattern

A string instance is considered valid if the regular expression matches the instance successfully.

public string $pattern = \OpenApi\Generator::UNDEFINED

$patternProperties

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.19.

public mixed $patternProperties = \OpenApi\Generator::UNDEFINED

$properties

public array<string|int, Property> $properties = \OpenApi\Generator::UNDEFINED

$propertyNames

http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.22.

public mixed $propertyNames = \OpenApi\Generator::UNDEFINED

$readOnly

Relevant only for Schema "properties" definitions.

public bool $readOnly = \OpenApi\Generator::UNDEFINED

Declares the property as "read only". This means that it may be sent as part of a response but should not be sent as part of the request. If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is false.

$ref

$ref See https://swagger.io/docs/specification/using-ref/.

public string $ref = \OpenApi\Generator::UNDEFINED

$required

An object instance is valid against this property if its property set contains all elements in this property's array value.

public array<string|int, string> $required = \OpenApi\Generator::UNDEFINED

$schema

The key into Components->schemas array.

public string $schema = \OpenApi\Generator::UNDEFINED

$title

Can be used to decorate a user interface with information about the data produced by this user interface. preferrably be short.

public string $title = \OpenApi\Generator::UNDEFINED

$type

The type of the schema/property. The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".

public string $type = \OpenApi\Generator::UNDEFINED

$uniqueItems

See http://json-schema.org/latest/json-schema-validation.html#anchor49.

public bool $uniqueItems = \OpenApi\Generator::UNDEFINED

$writeOnly

Relevant only for Schema "properties" definitions.

public bool $writeOnly = \OpenApi\Generator::UNDEFINED

Declares the property as "write only". Therefore, it may be sent as part of a request but should not be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is false.

$x

While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

public array<string|int, mixed> $x = \OpenApi\Generator::UNDEFINED

For further details see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#specificationExtensions The keys inside the array will be prefixed with x-.

$xml

This may be used only on properties schemas.

public Xml $xml = \OpenApi\Generator::UNDEFINED

It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property.

Methods

__construct()

public __construct(array<string|int, mixed> $properties) : mixed
Parameters
$properties : array<string|int, mixed>
Return values
mixed —

__get()

public __get(mixed $property) : mixed
Parameters
$property : mixed
Return values
mixed —

__set()

public __set(mixed $property, mixed $value) : mixed
Parameters
$property : mixed
$value : mixed
Return values
mixed —

identity()

Return a identity for easy debugging.

public identity() : string

Example: "@OA\Get(path="/pets")".

Return values
string —

isRoot()

An annotation is a root if it is the top-level / outermost annotation in a PHP docblock.

public isRoot() : bool
Return values
bool —

jsonSerialize()

Customize the way json_encode() renders the annotations.

public jsonSerialize() : mixed
Return values
mixed —

matchNested()

Find matching nested details.

public static matchNested(string $class) : null|object
Parameters
$class : string

the class to match

Return values
null|object —

key/value object or null

merge()

Merge given annotations to their mapped properties configured in static::$_nested.

public merge(array<string|int, AbstractAnnotation> $annotations[, bool $ignore = false ]) : array<string|int, AbstractAnnotation>

Annotations that couldn't be merged are added to the _unmerged array.

Parameters
$annotations : array<string|int, AbstractAnnotation>
$ignore : bool = false

Ignore unmerged annotations

Return values
array<string|int, AbstractAnnotation> —

The unmerged annotations

mergeProperties()

Merge the properties from the given object into this annotation.

public mergeProperties(object $object) : void

Prevents overwriting properties that are already configured.

Parameters
$object : object
Return values
void —

toJson()

Generate the documentation in YAML format.

public toJson([mixed $flags = null ]) : string
Parameters
$flags : mixed = null
Return values
string —

toYaml()

Generate the documentation in YAML format.

public toYaml([mixed $flags = null ]) : string
Parameters
$flags : mixed = null
Return values
string —

validate()

Validate annotation tree, and log notices & warnings.

public validate([array<string|int, mixed> $parents = [] ][, array<string|int, mixed> $skip = [] ][, string $ref = '' ]) : bool
Parameters
$parents : array<string|int, mixed> = []

the path of annotations above this annotation in the tree

$skip : array<string|int, mixed> = []

(prevent stack overflow, when traversing an infinite dependency graph)

$ref : string = ''
Return values
bool —

_identity()

Helper for generating the identity().

protected _identity(array<string|int, mixed> $properties) : string
Parameters
$properties : array<string|int, mixed>
Return values
string —

_validate()

Recursively validate all annotation properties.

private static _validate(array<string|int, mixed>|object $fields, array<string|int, mixed> $parents, array<string|int, mixed> $skip, string $baseRef) : bool
Parameters
$fields : array<string|int, mixed>|object
$parents : array<string|int, mixed>

the path of annotations above this annotation in the tree

$skip : array<string|int, mixed>

List of objects already validated

$baseRef : string
Return values
bool —

validateArrayType()

Validate array type.

private validateArrayType(mixed $value) : bool
Parameters
$value : mixed
Return values
bool —

validateDefaultTypes()

Validates default Open Api types.

private validateDefaultTypes(string $type, mixed $value) : bool
Parameters
$type : string

The property type

$value : mixed

The value to validate

Return values
bool —

validateType()

Validates the matching of the property value to a annotation type.

private validateType(string $type, mixed $value) : bool
Parameters
$type : string

The annotations property type

$value : mixed

The property value

Return values
bool —

Search results