Post
extends Operation
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 : mixed
- $_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.
- $callbacks : array<string|int, callable>
- A map of possible out-of band callbacks related to the parent operation.
- $deprecated : bool
- Declares this operation to be deprecated.
- $description : string
- A verbose explanation of the operation behavior.
- $externalDocs : ExternalDocumentation
- Additional external documentation for this operation.
- $method : string
- Key in the OpenApi "Path Item Object" for this operation.
- $operationId : string
- Unique string used to identify the operation.
- $parameters : array<string|int, Parameter>
- A list of parameters that are applicable for this operation.
- $path : string
- key in the OpenApi "Paths Object" for this operation.
- $requestBody : RequestBody
- The request body applicable for this operation.
- $responses : array<string|int, Response>
- The list of possible responses as they are returned from executing this operation.
- $security : array<string|int, mixed>
- A declaration of which security mechanisms can be used for this operation.
- $servers : array<string|int, Server>
- An alternative server array to service this operation.
- $summary : string
- A short summary of what the operation does.
- $tags : array<string|int, string>
- A list of tags for API documentation control.
- $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
= []
Examples: Info::clas => 'info', // Set @OA\Info annotation as the info property. Parameter::clas => ['parameters'], // Append @OA\Parameter annotations the parameters array. PathItem::clas => ['paths', 'path'], // Append @OA\PathItem annotations the paths array and use path as key.
$_parents
public
static mixed
$_parents
= [\OpenApi\Annotations\PathItem::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
= []
$_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.
$callbacks
A map of possible out-of band callbacks related to the parent operation.
public
array<string|int, callable>
$callbacks
= \OpenApi\Generator::UNDEFINED
The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses. The key value used to identify the callback object is an expression, evaluated at runtime, that identifies a URL to use for the callback operation.
$deprecated
Declares this operation to be deprecated.
public
bool
$deprecated
= \OpenApi\Generator::UNDEFINED
Consumers should refrain from usage of the declared operation. Default value is false.
$description
A verbose explanation of the operation behavior.
public
string
$description
= \OpenApi\Generator::UNDEFINED
CommonMark syntax MAY be used for rich text representation.
$externalDocs
Additional external documentation for this operation.
public
ExternalDocumentation
$externalDocs
= \OpenApi\Generator::UNDEFINED
$method
Key in the OpenApi "Path Item Object" for this operation.
public
string
$method
= 'post'
Tags
$operationId
Unique string used to identify the operation.
public
string
$operationId
= \OpenApi\Generator::UNDEFINED
The id must be unique among all operations described in the API. Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
$parameters
A list of parameters that are applicable for this operation.
public
array<string|int, Parameter>
$parameters
= \OpenApi\Generator::UNDEFINED
If a parameter is already defined at the Path Item, the new definition will override it but can never remove it. 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.
$path
key in the OpenApi "Paths Object" for this operation.
public
string
$path
= \OpenApi\Generator::UNDEFINED
$requestBody
The request body applicable for this operation.
public
RequestBody
$requestBody
= \OpenApi\Generator::UNDEFINED
The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored by consumers.
$responses
The list of possible responses as they are returned from executing this operation.
public
array<string|int, Response>
$responses
= \OpenApi\Generator::UNDEFINED
$security
A declaration of which security mechanisms can be used for this operation.
public
array<string|int, mixed>
$security
= \OpenApi\Generator::UNDEFINED
The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.
$servers
An alternative server array to service this operation.
public
array<string|int, Server>
$servers
= \OpenApi\Generator::UNDEFINED
If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by this value.
$summary
A short summary of what the operation does.
public
string
$summary
= \OpenApi\Generator::UNDEFINED
$tags
A list of tags for API documentation control.
public
array<string|int, string>
$tags
= \OpenApi\Generator::UNDEFINED
Tags can be used for logical grouping of operations by resources or any other qualifier.
$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