Documentation

Parameter extends AbstractAnnotation
in package

Application

The openapi annotation base class.

$_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\Schema::class => 'schema', \OpenApi\Annotations\Examples::class => ['examples', 'example'], \OpenApi\Annotations\Attachable::class => ['attachables']]

$_parents

Reverse mapping of $_nested with the allowed parent annotations.


    public
    static    array<string|int, string>
    $_parents
     = [\OpenApi\Annotations\Components::class, \OpenApi\Annotations\PathItem::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]

$_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
     = ['name', 'in']

$_types

Specify the type of the property.


    public
    static    array<string|int, mixed>
    $_types
     = ['name' => 'string', 'in' => ['query', 'header', 'path', 'cookie'], 'description' => 'string', 'style' => ['matrix', 'label', 'form', 'simple', 'spaceDelimited', 'pipeDelimited', 'deepObject'], 'required' => 'boolean']

$_unmerged

Annotations that couldn't be merged by mapping or postprocessing.


    public
        array<string|int, mixed>
    $_unmerged
     = []

$allowEmptyValue

Sets the ability to pass empty-valued parameters.


    public
        bool
    $allowEmptyValue
     = \OpenApi\Generator::UNDEFINED

This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.

$allowReserved

Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.


    public
        bool
    $allowReserved
     = \OpenApi\Generator::UNDEFINED

This property only applies to parameters with an in value of query. The default value is false.

$attachables

Arbitrary attachables for this annotation.


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

These will be ignored but can be used for custom processing.

$content

A map containing the representations for the parameter.


    public
        array<string|int, MediaType>
    $content
     = \OpenApi\Generator::UNDEFINED

The key is the media type and the value describes it. The map must only contain one entry.

$deepObject

Provides a simple way of rendering nested objects using form parameters.


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

$deprecated

Specifies that a parameter is deprecated and should be transitioned out of usage.


    public
        bool
    $deprecated
     = \OpenApi\Generator::UNDEFINED

$description

A brief description of the parameter.


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

This could contain examples of use. CommonMark syntax may be used for rich text representation.

$example

Example of the media type.


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

The example should match the specified schema and encoding properties if present. The example object is mutually exclusive of the examples object. Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

$examples

Examples of the media type.


    public
        array<string|int, mixed>
    $examples
     = \OpenApi\Generator::UNDEFINED

Each example should contain a value in the correct format as specified in the parameter encoding. The examples object is mutually exclusive of the example object. Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.

$explode

When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map.


    public
        bool
    $explode
     = \OpenApi\Generator::UNDEFINED

For other types of parameters this property has no effect. When style is form, the default value is true. For all other styles, the default value is false.

$form

Form style parameters defined by https://tools.ietf.org/html/rfc6570#section-3.2.8 This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.


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

$in

The location of the parameter.


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

Possible values are "query", "header", "path" or "cookie".

$label

Label style parameters defined by https://tools.ietf.org/html/rfc6570#section-3.2.5.


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

$matrix

Path-style parameters defined by https://tools.ietf.org/html/rfc6570#section-3.2.7.


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

$name

The name of the parameter.


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

Parameter names are case sensitive. If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object. If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored. For all other cases, the name corresponds to the parameter name used by the in property.

$parameter

The key into Components->parameters or PathItem->parameters array.


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

$pipeDelimited

Pipe separated array values.


    public
        array<string|int, mixed>
    $pipeDelimited
     = \OpenApi\Generator::UNDEFINED

This option replaces collectionFormat equal to pipes from OpenAPI 2.0.

$ref

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


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

$required

Determines whether this parameter is mandatory.


    public
        bool
    $required
     = \OpenApi\Generator::UNDEFINED

If the parameter location is "path", this property is required and its value must be true. Otherwise, the property may be included and its default value is false.

$schema

The schema defining the type used for the parameter.


    public
        Schema
    $schema
     = \OpenApi\Generator::UNDEFINED

$simple

Simple style parameters defined by https://tools.ietf.org/html/rfc6570#section-3.2.2 This option replaces collectionFormat with a csv value from OpenAPI 2.0.


    public
        array<string|int, mixed>
    $simple
     = \OpenApi\Generator::UNDEFINED

$spaceDelimited

Space separated array values.


    public
        array<string|int, mixed>
    $spaceDelimited
     = \OpenApi\Generator::UNDEFINED

This option replaces collectionFormat equal to ssv from OpenAPI 2.0.

$style

Describes how the parameter value will be serialized depending on the type of the parameter value.


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

Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

$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-.

__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

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

Return values

bool —

Parameter extends AbstractAnnotation in package Application

Tags

Table of Contents

Properties

$_blacklist

$_context

$_nested

Tags

$_parents

Tags

$_required

Tags

$_types

Tags

$_unmerged

$allowEmptyValue

$allowReserved

$attachables

$content

$deepObject

$deprecated

$description

$example

$examples

$explode

$form

$in

$label

$matrix

$name

$parameter

$pipeDelimited

$ref

$required

$schema

$simple

$spaceDelimited

$style

$x

Methods

__construct()

Parameters

Return values

__debugInfo()

Return values

__get()

Parameters

Return values

__set()

Parameters

Return values

identity()

Tags

Return values

isRoot()

Return values

jsonSerialize()

Return values

matchNested()

Parameters

Return values

merge()

Parameters

Return values

mergeProperties()

Parameters

Return values

toJson()

Parameters

Return values

toYaml()

Parameters

Return values

validate()

Parameters

Tags

Return values

_identity()

Parameters

Return values

Parameter extends AbstractAnnotation
in package

Application