1
|
|
|
<?php |
2
|
|
|
|
3
|
|
|
namespace erasys\OpenApi\Spec\v3; |
4
|
|
|
|
5
|
|
|
/** |
6
|
|
|
* Describes a single API operation on a path. |
7
|
|
|
* |
8
|
|
|
* @see https://swagger.io/specification/#operationObject |
9
|
|
|
*/ |
10
|
|
|
class Operation extends AbstractObject implements ExtensibleInterface |
11
|
|
|
{ |
12
|
|
|
/** |
13
|
|
|
* REQUIRED. The list of possible responses as they are returned from executing this operation. |
14
|
|
|
* |
15
|
|
|
* Map between the response HTTP status code (as a string) and the definition object. |
16
|
|
|
* |
17
|
|
|
* The documentation is not necessarily expected to cover all possible HTTP response codes because they may not be |
18
|
|
|
* known in advance. However, documentation is expected to cover a successful operation response and any known |
19
|
|
|
* errors. The "default" code MAY be used as a default response object for all HTTP codes that are not covered |
20
|
|
|
* individually by the specification. |
21
|
|
|
* |
22
|
|
|
* The Responses Object MUST contain at least one response code, and it SHOULD be the response for a successful |
23
|
|
|
* operation call. |
24
|
|
|
* |
25
|
|
|
* Any HTTP status code can be used as the property name, but only one property per code, to describe the |
26
|
|
|
* expected response for that HTTP status code. A Reference Object can link to a response that is defined in the |
27
|
|
|
* OpenAPI Object's components/responses section. This field MUST be enclosed in quotation marks (for example, |
28
|
|
|
* "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the |
29
|
|
|
* uppercase wildcard character X. For example, 2XX represents all response codes between [200-299]. The following |
30
|
|
|
* range definitions are allowed: 1XX, 2XX, 3XX, 4XX, and 5XX. If a response range is defined using an explicit |
31
|
|
|
* code, the explicit code definition takes precedence over the range definition for that code. |
32
|
|
|
* |
33
|
|
|
* @see https://swagger.io/specification/#responsesObject |
34
|
|
|
* |
35
|
|
|
* @var Response[]|Reference[] array<string, Response>|array<string, Reference> |
36
|
|
|
*/ |
37
|
|
|
public $responses; |
38
|
|
|
|
39
|
|
|
/** |
40
|
|
|
* A list of tags for API documentation control. |
41
|
|
|
* Tags can be used for logical grouping of operations by resources or any other qualifier. |
42
|
|
|
* |
43
|
|
|
* @var string[] |
44
|
|
|
*/ |
45
|
|
|
public $tags; |
46
|
|
|
|
47
|
|
|
/** |
48
|
|
|
* A short summary of what the operation does. |
49
|
|
|
* |
50
|
|
|
* @var string |
51
|
|
|
*/ |
52
|
|
|
public $summary; |
53
|
|
|
|
54
|
|
|
/** |
55
|
|
|
* A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text representation. |
56
|
|
|
* |
57
|
|
|
* @var string |
58
|
|
|
*/ |
59
|
|
|
public $description; |
60
|
|
|
|
61
|
|
|
/** |
62
|
|
|
* Additional external documentation for this operation. |
63
|
|
|
* |
64
|
|
|
* @var ExternalDocumentation |
65
|
|
|
*/ |
66
|
|
|
public $externalDocs; |
67
|
|
|
|
68
|
|
|
/** |
69
|
|
|
* Unique string used to identify the operation. |
70
|
|
|
* |
71
|
|
|
* The id MUST be unique among all operations described in the API. |
72
|
|
|
* Tools and libraries MAY use the operationId to uniquely identify an operation, |
73
|
|
|
* therefore, it is RECOMMENDED to follow common programming naming conventions. |
74
|
|
|
* |
75
|
|
|
* @var string |
76
|
|
|
*/ |
77
|
|
|
public $operationId; |
78
|
|
|
|
79
|
|
|
/** |
80
|
|
|
* A list of parameters that are applicable for this operation. |
81
|
|
|
* If a parameter is already defined at the Path Item, the new definition will override it but can never remove it. |
82
|
|
|
* The list MUST NOT include duplicated parameters. |
83
|
|
|
* A unique parameter is defined by a combination of a name and location. |
84
|
|
|
* The list can use the Reference Object to link to parameters that are defined at the |
85
|
|
|
* OpenAPI Object's components/parameters. |
86
|
|
|
* |
87
|
|
|
* @see https://swagger.io/specification/#parameterName |
88
|
|
|
* @see https://swagger.io/specification/#parameterIn |
89
|
|
|
* @see https://swagger.io/specification/#referenceObject |
90
|
|
|
* @see https://swagger.io/specification/#componentsParameters |
91
|
|
|
* |
92
|
|
|
* @var Parameter[]|Reference[] |
93
|
|
|
*/ |
94
|
|
|
public $parameters; |
95
|
|
|
|
96
|
|
|
/** |
97
|
|
|
* The request body applicable for this operation. |
98
|
|
|
* The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 |
99
|
|
|
* has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, |
100
|
|
|
* requestBody SHALL be ignored by consumers. |
101
|
|
|
* |
102
|
|
|
* @see https://tools.ietf.org/html/rfc7231#section-4.3.1 |
103
|
|
|
* |
104
|
|
|
* @var RequestBody|Reference |
105
|
|
|
*/ |
106
|
|
|
public $requestBody; |
107
|
|
|
|
108
|
|
|
/** |
109
|
|
|
* A map of possible out-of band callbacks (aka. web hooks) related to the parent operation. |
110
|
|
|
* The key is a unique identifier for the Callback Object. |
111
|
|
|
* Each value in the map is a Callback Object that describes a request that may be initiated by |
112
|
|
|
* the API provider and the expected responses. The key value used to identify the callback object |
113
|
|
|
* is an expression, evaluated at runtime, that identifies a URL to use for the callback operation. |
114
|
|
|
* |
115
|
|
|
* @see https://swagger.io/specification/#callbackObject |
116
|
|
|
* |
117
|
|
|
* @var PathItem[]|Reference[] array<string, PathItem>|array<string, Reference> |
118
|
|
|
*/ |
119
|
|
|
public $callbacks; |
120
|
|
|
|
121
|
|
|
/** |
122
|
|
|
* Declares this operation to be deprecated. |
123
|
|
|
* Consumers SHOULD refrain from usage of the declared operation. Default value is false (if not specified). |
124
|
|
|
* |
125
|
|
|
* @var bool |
126
|
|
|
*/ |
127
|
|
|
public $deprecated; |
128
|
|
|
|
129
|
|
|
/** |
130
|
|
|
* A declaration of which security mechanisms can be used for this operation. |
131
|
|
|
* The list of values includes alternative security requirement objects that can be used |
132
|
|
|
* Only one of the security requirement objects need to be satisfied to authorize a request. |
133
|
|
|
* This definition overrides any declared top-level security. To remove a top-level security declaration, |
134
|
|
|
* an empty array can be used. |
135
|
|
|
* |
136
|
|
|
* Each name (key) MUST correspond to a security scheme which is declared in the Security Schemes |
137
|
|
|
* under the Components Object. If the security scheme is of type "oauth2" or "openIdConnect", |
138
|
|
|
* then the value is a list of scope names required for the execution. For other security scheme types, |
139
|
|
|
* the array MUST be empty. |
140
|
|
|
* |
141
|
|
|
* @example {"api_key": []} |
142
|
|
|
* |
143
|
|
|
* @see https://swagger.io/specification/#securityRequirementObject |
144
|
|
|
* @var string[] array<string, string[]> |
145
|
|
|
*/ |
146
|
|
|
public $security; |
147
|
|
|
|
148
|
|
|
/** |
149
|
|
|
* An alternative server array to service this operation. |
150
|
|
|
* If an alternative server object is specified at the Path Item Object or Root level, |
151
|
|
|
* it will be overridden by this value. |
152
|
|
|
* |
153
|
|
|
* @var Server[] |
154
|
|
|
*/ |
155
|
|
|
public $servers; |
156
|
|
|
|
157
|
|
|
/** |
158
|
|
|
* @param Response[]|Reference[] $responses |
159
|
|
|
* @param string|null $operationId |
160
|
|
|
* @param string|null $summary |
161
|
|
|
* @param array $additionalProperties |
162
|
|
|
*/ |
163
|
3 |
|
public function __construct( |
164
|
|
|
array $responses, |
165
|
|
|
string $operationId = null, |
166
|
|
|
string $summary = null, |
167
|
|
|
array $additionalProperties = [] |
168
|
|
|
) { |
169
|
3 |
|
parent::__construct($additionalProperties); |
170
|
3 |
|
$this->responses = $responses; |
171
|
3 |
|
$this->operationId = $operationId; |
172
|
3 |
|
$this->summary = $summary; |
173
|
3 |
|
} |
174
|
|
|
} |
175
|
|
|
|