Debian Codegraph @

vendor/zircote/swagger-php/src/Annotations/Operation.php

raw
1 <?php declare(strict_types=1);
2
3 /**
4 * @license Apache 2.0
5 */
6
7 namespace OpenApi\Annotations;
8
9 use OpenApi\Analysis;
10 use OpenApi\Annotations as OA;
11 use OpenApi\Generator;
12
13 /**
14 * Base class for <code>@OA\Get</code>, <code>@OA\Post</code>, <code>@OA\Put</code>, etc.
15 *
16 * Describes a single API operation on a path.
17 *
18 * @see [Operation Object](https://spec.openapis.org/oas/v3.1.1.html#operation-object)
19 *
20 * @Annotation
21 */
22 abstract class Operation extends AbstractAnnotation
23 {
24 /**
25 * Key in the OpenApi "Paths Object" for this operation.
26 *
27 * @var string
28 */
29 public $path = Generator::UNDEFINED;
30
31 /**
32 * A list of tags for API documentation control.
33 *
34 * Tags can be used for logical grouping of operations by resources or any other qualifier.
35 *
36 * @var list<string>
37 */
38 public $tags = Generator::UNDEFINED;
39
40 /**
41 * Key in the OpenApi "Path Item Object" for this operation.
42 *
43 * Allowed values: 'get', 'post', put', 'patch', 'delete', 'options', 'head' and 'trace'.
44 *
45 * @var string
46 */
47 public $method = Generator::UNDEFINED;
48
49 /**
50 * A short summary of what the operation does.
51 *
52 * @var string
53 */
54 public $summary = Generator::UNDEFINED;
55
56 /**
57 * A verbose explanation of the operation behavior.
58 *
59 * CommonMark syntax MAY be used for rich text representation.
60 *
61 * @var string
62 */
63 public $description = Generator::UNDEFINED;
64
65 /**
66 * Additional external documentation for this operation.
67 *
68 * @var ExternalDocumentation
69 */
70 public $externalDocs = Generator::UNDEFINED;
71
72 /**
73 * Unique string used to identify the operation.
74 *
75 * The id must be unique among all operations described in the API.
76 * Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
77 * follow common programming naming conventions.
78 *
79 * @var string
80 */
81 public $operationId = Generator::UNDEFINED;
82
83 /**
84 * A list of parameters that are applicable for this operation.
85 *
86 * If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
87 * The list must not include duplicated parameters.
88 *
89 * A unique parameter is defined by a combination of a name and location.
90 *
91 * The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
92 * components/parameters.
93 *
94 * @var list<Parameter>
95 */
96 public $parameters = Generator::UNDEFINED;
97
98 /**
99 * The request body applicable for this operation.
100 *
101 * The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
102 * defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
103 * by consumers.
104 *
105 * @var RequestBody
106 */
107 public $requestBody = Generator::UNDEFINED;
108
109 /**
110 * The list of possible responses as they are returned from executing this operation.
111 *
112 * @var list<Response>
113 */
114 public $responses = Generator::UNDEFINED;
115
116 /**
117 * A map of possible out-of band callbacks related to the parent operation.
118 *
119 * The key is a unique identifier for the Callback Object.
120 *
121 * Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
122 * and the expected responses. The key value used to identify the callback object is an expression, evaluated at
123 * runtime, that identifies a URL to use for the callback operation.
124 *
125 * @var array
126 */
127 public $callbacks = Generator::UNDEFINED;
128
129 /**
130 * Declares this operation to be deprecated.
131 *
132 * Consumers should refrain from usage of the declared operation.
133 *
134 * Default value is false.
135 *
136 * @var bool
137 */
138 public $deprecated = Generator::UNDEFINED;
139
140 /**
141 * A declaration of which security mechanisms can be used for this operation.
142 *
143 * The list of values includes alternative security requirement objects that can be used.
144 *
145 * Only one of the security requirement objects need to be satisfied to authorize a request.
146 *
147 * This definition overrides any declared top-level security.
148 * To remove a top-level security declaration, an empty array can be used.
149 *
150 * @var array
151 */
152 public $security = Generator::UNDEFINED;
153
154 /**
155 * An alternative server array to service this operation.
156 *
157 * If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
158 * this value.
159 *
160 * @var list<Server>
161 */
162 public $servers = Generator::UNDEFINED;
163
164 /**
165 * @inheritdoc
166 */
167 public static $_required = ['responses'];
168
169 /**
170 * @inheritdoc
171 */
172 public static $_types = [
173 'path' => 'string',
174 'method' => 'string',
175 'tags' => '[string]',
176 'summary' => 'string',
177 'description' => 'string',
178 'deprecated' => 'boolean',
179 ];
180
181 /**
182 * @inheritdoc
183 */
184 public static $_nested = [
185 Parameter::class => ['parameters'],
186 PathParameter::class => ['parameters'],
187 Response::class => ['responses', 'response'],
188 ExternalDocumentation::class => 'externalDocs',
189 Server::class => ['servers'],
190 RequestBody::class => 'requestBody',
191 Attachable::class => ['attachables'],
192 ];
193
194 public function jsonSerialize(): \stdClass
195 {
196 $data = parent::jsonSerialize();
197
198 unset($data->method);
199 unset($data->path);
200
201 // ensure security elements are object
202 if (isset($data->security) && is_array($data->security)) {
203 foreach ($data->security as $key => $scheme) {
204 $data->security[$key] = (object) $scheme;
205 }
206 }
207
208 return $data;
209 }
210
211 #[\Override]
212 public function validate(?Analysis $analysis = null, string $version = OpenApi::DEFAULT_VERSION, ?object $context = null): bool
213 {
214 $isValid = parent::validate($analysis, $version, $context);
215
216 if (!Generator::isDefault($this->responses)) {
217 foreach ($this->responses as $response) {
218 if (!Generator::isDefault($response->response) && $response->response !== 'default' && preg_match('/^([12345]{1}\d{2})|([12345]{1}XX)$/', (string) $response->response) === 0) {
219 $this->_context->logger->warning('Invalid value "' . $response->response . '" for ' . $response->identity([]) . '->response, expecting "default", a HTTP Status Code or HTTP Status Code range definition in ' . $response->_context);
220 $isValid = false;
221 }
222 }
223 }
224
225 if (!Generator::isDefault($this->operationId)) {
226 if (!property_exists($context, 'operationIds')) {
227 $context->operationIds = [];
228 }
229
230 if (in_array($this->operationId, $context->operationIds)) {
231 $this->_context->logger->warning('operationId must be unique. Duplicate value found: "' . $this->operationId . '"');
232 $isValid = false;
233 }
234
235 $context->operationIds[] = $this->operationId;
236 }
237
238 return $isValid;
239 }
240 }