Attachable
extends AbstractAnnotation
in package
The openapi annotation base class.
Tags
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.
- $attachables : mixed
- Arbitrary attachables for this annotation.
- $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.
- __construct() : mixed
- __debugInfo() : mixed
- __get() : mixed
- __set() : mixed
- allowedParents() : array<string|int, mixed>
- Allows to type hint a specific parent annotation class.
- 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']
$_context
public
Context
$_context
$_nested
Declarative mapping of Annotation types to properties.
public
static array<string|int, mixed>
$_nested
= []
Examples: Info::clas => 'info', // Set @OA\Info annotation as the info property. Parameter::clas => ['parameters'], // Append @OA\Parameter annotations the parameters array. PathItem::clas => ['paths', 'path'], // Append @OA\PathItem annotations the paths array and use path as key.
$_parents
Reverse mapping of $_nested with the allowed parent annotations.
public
static array<string|int, string>
$_parents
= [\OpenApi\Annotations\AdditionalProperties::class, \OpenApi\Annotations\Components::class, \OpenApi\Annotations\Contact::class, \OpenApi\Annotations\Delete::class, \OpenApi\Annotations\Discriminator::class, \OpenApi\Annotations\Examples::class, \OpenApi\Annotations\ExternalDocumentation::class, \OpenApi\Annotations\Flow::class, \OpenApi\Annotations\Get::class, \OpenApi\Annotations\Head::class, \OpenApi\Annotations\Header::class, \OpenApi\Annotations\Info::class, \OpenApi\Annotations\Items::class, \OpenApi\Annotations\JsonContent::class, \OpenApi\Annotations\License::class, \OpenApi\Annotations\Link::class, \OpenApi\Annotations\MediaType::class, \OpenApi\Annotations\OpenApi::class, \OpenApi\Annotations\Operation::class, \OpenApi\Annotations\Options::class, \OpenApi\Annotations\Parameter::class, \OpenApi\Annotations\Patch::class, \OpenApi\Annotations\PathItem::class, \OpenApi\Annotations\Post::class, \OpenApi\Annotations\Property::class, \OpenApi\Annotations\Put::class, \OpenApi\Annotations\RequestBody::class, \OpenApi\Annotations\Response::class, \OpenApi\Annotations\Schema::class, \OpenApi\Annotations\SecurityScheme::class, \OpenApi\Annotations\Server::class, \OpenApi\Annotations\ServerVariable::class, \OpenApi\Annotations\Tag::class, \OpenApi\Annotations\Trace::class, \OpenApi\Annotations\Xml::class, \OpenApi\Annotations\XmlContent::class]
Tags
$_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
= []
Examples: 'name' => 'string' // a string 'required' => 'boolean', // true or false 'tags' => '[string]', // array containing strings 'in' => ["query", "header", "path", "formData", "body"] // must be one on these 'oneOf' => [Schema::class] // array of schema objects.
$_unmerged
Annotations that couldn't be merged by mapping or postprocessing.
public
array<string|int, mixed>
$_unmerged
= []
$attachables
Arbitrary attachables for this annotation.
public
mixed
$attachables
= \OpenApi\Generator::UNDEFINED
These will be ignored but can be used for custom processing.
$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-.
Methods
__construct()
public
__construct(array<string|int, mixed> $properties) : mixed
Parameters
- $properties : array<string|int, mixed>
Return values
mixed —__debugInfo()
public
__debugInfo() : 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 —allowedParents()
Allows to type hint a specific parent annotation class.
public
allowedParents() : array<string|int, mixed>
Allows to implement custom annotations that are limited to a subset of potential parent annotation classes. This is most likely going to be a v4 (PHP 8.1) PHP attribute feature only.
Return values
array<string|int, mixed> —List of valid parent annotation classes. If `null`` the default nesting rules apply.
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 —nested()
Wrap the context with a reference to the annotation it is nested in.
private
nested(AbstractAnnotation $annotation, Context $nestedContext) : AbstractAnnotation
Parameters
- $annotation : AbstractAnnotation
- $nestedContext : Context
Return values
AbstractAnnotation —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