ExternalDocumentation
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.
- $description : string
- A short description of the target documentation. GFM syntax can be used for rich text representation.
- $url : string
- The URL for the target documentation.
- $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
- 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
= [\OpenApi\Annotations\Attachable::class => ['attachables']]
Tags
$_parents
Reverse mapping of $_nested with the allowed parent annotations.
public
static array<string|int, string>
$_parents
= [\OpenApi\Annotations\OpenApi::class, \OpenApi\Annotations\Tag::class, \OpenApi\Annotations\Schema::class, \OpenApi\Annotations\AdditionalProperties::class, \OpenApi\Annotations\Property::class, \OpenApi\Annotations\Operation::class, \OpenApi\Annotations\Get::class, \OpenApi\Annotations\Post::class, \OpenApi\Annotations\Put::class, \OpenApi\Annotations\Delete::class, \OpenApi\Annotations\Patch::class, \OpenApi\Annotations\Head::class, \OpenApi\Annotations\Options::class, \OpenApi\Annotations\Trace::class, \OpenApi\Annotations\Items::class, \OpenApi\Annotations\JsonContent::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
= ['url']
Tags
$_types
Specify the type of the property.
public
static array<string|int, mixed>
$_types
= ['description' => 'string', 'url' => 'string']
Tags
$_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.
$description
A short description of the target documentation. GFM syntax can be used for rich text representation.
public
string
$description
= \OpenApi\Generator::UNDEFINED
$url
The URL for the target documentation.
public
string
$url
= \OpenApi\Generator::UNDEFINED
$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 —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