Skip to content

Latest commit

 

History

History
755 lines (300 loc) · 7.99 KB

PathItem.md

File metadata and controls

755 lines (300 loc) · 7.99 KB

PathItem

The openapi annotation base class.

Properties

ref

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

public string $ref

path

key for the Path Object (OpenApi->paths array).

public string $path

summary

An optional, string summary, intended to apply to all operations in this path.

public string $summary

get

A definition of a GET operation on this path.

public \OpenApi\Annotations\Get $get

put

A definition of a PUT operation on this path.

public \OpenApi\Annotations\Put $put

post

A definition of a POST operation on this path.

public \OpenApi\Annotations\Post $post

delete

A definition of a DELETE operation on this path.

public \OpenApi\Annotations\Delete $delete

options

A definition of a OPTIONS operation on this path.

public \OpenApi\Annotations\Options $options

head

A definition of a HEAD operation on this path.

public \OpenApi\Annotations\Head $head

patch

A definition of a PATCH operation on this path.

public \OpenApi\Annotations\Patch $patch

trace

A definition of a TRACE operation on this path.

public \OpenApi\Annotations\Trace $trace

servers

An alternative server array to service all operations in this path.

public \OpenApi\Annotations\Server[] $servers

parameters

A list of parameters that are applicable for all the operations described under this path.

public \OpenApi\Annotations\Parameter[] $parameters

These parameters can be overridden at the operation level, but cannot be removed there. The list must not include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's components/parameters.

_types

Specify the type of the property.

public static array $_types
  • This property is static.

_nested

Declarative mapping of Annotation types to properties.

public static array $_nested
  • This property is static.

_parents

Reverse mapping of $_nested with the allowed parent annotations.

public static string[] $_parents
  • This property is static.

Inherited methods

__construct

public __construct(array $properties): mixed

Parameters:

Parameter Type Description
$properties array

__get

public __get(mixed $property): mixed

Parameters:

Parameter Type Description
$property mixed

__set

public __set(mixed $property, mixed $value): mixed

Parameters:

Parameter Type Description
$property mixed
$value mixed

merge

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

public merge(\OpenApi\Annotations\AbstractAnnotation[] $annotations, bool $ignore = false): \OpenApi\Annotations\AbstractAnnotation[]

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

Parameters:

Parameter Type Description
$annotations \OpenApi\Annotations\AbstractAnnotation[]
$ignore bool Ignore unmerged annotations

Return Value:

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:

Parameter Type Description
$object object

toYaml

Generate the documentation in YAML format.

public toYaml(mixed $flags = null): string

Parameters:

Parameter Type Description
$flags mixed

toJson

Generate the documentation in YAML format.

public toJson(mixed $flags = null): string

Parameters:

Parameter Type Description
$flags mixed

__debugInfo

public __debugInfo(): mixed

jsonSerialize

Customize the way json_encode() renders the annotations.

public jsonSerialize(): mixed

validate

Validate annotation tree, and log notices & warnings.

public validate(array $parents = [], array $skip = [], string $ref = ''): bool

Parameters:

Parameter Type Description
$parents array the path of annotations above this annotation in the tree
$skip array (prevent stack overflow, when traversing an infinite dependency graph)
$ref string

_validate

Recursively validate all annotation properties.

private static _validate(array|object $fields, array $parents, array $skip, string $baseRef): bool
  • This method is static.

Parameters:

Parameter Type Description
$fields array|object
$parents array the path of annotations above this annotation in the tree
$skip array List of objects already validated
$baseRef string

identity

Return a identity for easy debugging.

public identity(): string

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

isRoot

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

public isRoot(): bool

matchNested

Find matching nested details.

public static matchNested(string $class): null|object
  • This method is static.

Parameters:

Parameter Type Description
$class string the class to match

Return Value:

key/value object or null

_identity

Helper for generating the identity().

protected _identity(array $properties): string

Parameters:

Parameter Type Description
$properties array

validateType

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

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

Parameters:

Parameter Type Description
$type string The annotations property type
$value mixed The property value

validateDefaultTypes

Validates default Open Api types.

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

Parameters:

Parameter Type Description
$type string The property type
$value mixed The value to validate

validateArrayType

Validate array type.

private validateArrayType(mixed $value): bool

Parameters:

Parameter Type Description
$value mixed

nested

Wrap the context with a reference to the annotation it is nested in.

private nested(\OpenApi\Annotations\AbstractAnnotation $annotation, \OpenApi\Context $nestedContext): \OpenApi\Annotations\AbstractAnnotation

Parameters:

Parameter Type Description
$annotation \OpenApi\Annotations\AbstractAnnotation
$nestedContext \OpenApi\Context