Documentation

Link extends AbstractAnnotation
in package

The openapi annotation base class.

Tags
Annotation

A "Link Object" https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#link-object

The Link object represents a possible design-time link for a response. The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations. Unlike dynamic links (i.e. links provided in the response payload), the OA linking mechanism does not require link information in the runtime response. For computing links, and providing instructions to execute them, a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.

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 description of the link.
$link  : string
The key into MediaType->links array.
$operationId  : string
The name of an existing, resolvable OA operation, as defined with a unique operationId.
$operationRef  : string
A relative or absolute reference to an OA operation.
$parameters  : mixed
A map representing parameters to pass to an operation as specified with operationId or identified via operationRef.
$ref  : string
$ref See https://swagger.io/docs/specification/using-ref/.
$requestBody  : mixed
A literal value or {expression} to use as a request body when calling the target operation.
$server  : Server
A server object to be used by the target operation.
$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']

$_nested

Declarative mapping of Annotation types to properties.

public static array<string|int, mixed> $_nested = [\OpenApi\Annotations\Server::class => 'server', \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\Response::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 = []

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.

$description

A description of the link.

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

CommonMark syntax may be used for rich text representation.

$link

The key into MediaType->links array.

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

$operationId

The name of an existing, resolvable OA operation, as defined with a unique operationId.

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

This field is mutually exclusive of the operationRef field.

$operationRef

A relative or absolute reference to an OA operation.

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

This field is mutually exclusive of the operationId field, and must point to an Operation Object. Relative operationRef values may be used to locate an existing Operation Object in the OpenAPI definition.

$parameters

A map representing parameters to pass to an operation as specified with operationId or identified via operationRef.

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

The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use the same parameter name in different locations (e.g. path.id).

$ref

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

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

$requestBody

A literal value or {expression} to use as a request body when calling the target operation.

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

$server

A server object to be used by the target operation.

public Server $server = \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 —

__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