OpenApi
extends AbstractAnnotation
in package
The openapi annotation base class.
Tags
Table of Contents
- $_analysis : Analysis
- $_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.
- $components : Components
- An element to hold various components for the specification.
- $externalDocs : ExternalDocumentation
- Additional external documentation.
- $info : Info
- Provides metadata about the API. The metadata may be used by tooling as required.
- $openapi : string
- The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.
- $paths : array<string|int, PathItem>
- The available paths and operations for the API.
- $security : array<string|int, mixed>
- Lists the required security schemes to execute this operation.
- $servers : array<string|int, Server>
- An array of Server Objects, which provide connectivity information to a target server.
- $tags : array<string|int, Tag>
- A list of tags used by the specification with additional metadata.
- $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.
- ref() : mixed
- Look up an annotation with a $ref url.
- saveAs() : void
- Save the OpenAPI documentation to a file.
- 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.
- resolveRef() : mixed
- Recursive helper for ref().
- 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
$_analysis
public
Analysis
$_analysis
= \OpenApi\Generator::UNDEFINED
$_blacklist
List of properties are blacklisted from the JSON output.
public
static array<string|int, mixed>
$_blacklist
= ['_context', '_unmerged', '_analysis']
Tags
$_context
public
Context
$_context
$_nested
Declarative mapping of Annotation types to properties.
public
static array<string|int, mixed>
$_nested
= [\OpenApi\Annotations\Info::class => 'info', \OpenApi\Annotations\Server::class => ['servers'], \OpenApi\Annotations\PathItem::class => ['paths', 'path'], \OpenApi\Annotations\Components::class => 'components', \OpenApi\Annotations\Tag::class => ['tags'], \OpenApi\Annotations\ExternalDocumentation::class => 'externalDocs', \OpenApi\Annotations\Attachable::class => ['attachables']]
Tags
$_parents
Reverse mapping of $_nested with the allowed parent annotations.
public
static array<string|int, string>
$_parents
= []
$_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
= ['openapi', 'info', 'paths']
Tags
$_types
Specify the type of the property.
public
static array<string|int, mixed>
$_types
= []
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.
$components
An element to hold various components for the specification.
public
Components
$components
= \OpenApi\Generator::UNDEFINED
$externalDocs
Additional external documentation.
public
ExternalDocumentation
$externalDocs
= \OpenApi\Generator::UNDEFINED
$info
Provides metadata about the API. The metadata may be used by tooling as required.
public
Info
$info
= \OpenApi\Generator::UNDEFINED
$openapi
The semantic version number of the OpenAPI Specification version that the OpenAPI document uses.
public
string
$openapi
= '3.0.0'
The openapi field should be used by tooling specifications and clients to interpret the OpenAPI document. This is not related to the API info.version string.
$paths
The available paths and operations for the API.
public
array<string|int, PathItem>
$paths
= \OpenApi\Generator::UNDEFINED
$security
Lists the required security schemes to execute this operation.
public
array<string|int, mixed>
$security
= \OpenApi\Generator::UNDEFINED
The name used for each property must correspond to a security scheme declared in the Security Schemes under the Components Object. Security Requirement Objects that contain multiple schemes require that all schemes must be satisfied for a request to be authorized. This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information. When a list of Security Requirement Objects is defined on the Open API object or Operation Object, only one of Security Requirement Objects in the list needs to be satisfied to authorize the request.
$servers
An array of Server Objects, which provide connectivity information to a target server.
public
array<string|int, Server>
$servers
= \OpenApi\Generator::UNDEFINED
If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.
$tags
A list of tags used by the specification with additional metadata.
public
array<string|int, Tag>
$tags
= \OpenApi\Generator::UNDEFINED
The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list must be unique.
$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 —ref()
Look up an annotation with a $ref url.
public
ref(string $ref) : mixed
Parameters
- $ref : string
-
The $ref value, for example: "#/components/schemas/Product"
Return values
mixed —saveAs()
Save the OpenAPI documentation to a file.
public
saveAs(string $filename[, string $format = 'auto' ]) : void
Parameters
- $filename : string
- $format : string = 'auto'
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 = null ][, array<string|int, mixed> $skip = null ][, string $ref = '' ]) : bool
Parameters
- $parents : array<string|int, mixed> = null
-
the path of annotations above this annotation in the tree
- $skip : array<string|int, mixed> = null
-
(prevent stack overflow, when traversing an infinite dependency graph)
- $ref : string = ''
Tags
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 —resolveRef()
Recursive helper for ref().
private
static resolveRef(string $ref, string $resolved, mixed $container, array<string|int, mixed> $mapping) : mixed
Parameters
- $ref : string
- $resolved : string
- $container : mixed
- $mapping : array<string|int, mixed>
Return values
mixed —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