Debian Codegraph @

vendor/zircote/swagger-php/src/Annotations/Parameter.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\Generator;
11
12 /**
13 * Describes a single operation parameter.
14 *
15 * A unique parameter is defined by a combination of a name and location.
16 *
17 * @see [Parameter Object](https://spec.openapis.org/oas/v3.1.1.html#parameter-object)
18 *
19 * @Annotation
20 */
21 class Parameter extends AbstractAnnotation
22 {
23 /**
24 * The relative or absolute path to the endpoint.
25 *
26 * @see [Reference Object](https://spec.openapis.org/oas/v3.1.1.html#reference-object)
27 *
28 * @var string|class-string|object
29 */
30 public $ref = Generator::UNDEFINED;
31
32 /**
33 * The key into <code>Components::parameters</code> or <code>PathItem::parameters</code> array.
34 *
35 * @var string
36 */
37 public $parameter = Generator::UNDEFINED;
38
39 /**
40 * The (case-sensitive) name of the parameter.
41 *
42 * If in is "path", the name field must correspond to the associated path segment from the path field in the Paths Object.
43 *
44 * If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition shall be ignored.
45 * For all other cases, the name corresponds to the parameter name used by the in property.
46 *
47 * @var string
48 */
49 public $name = Generator::UNDEFINED;
50
51 /**
52 * The location of the parameter.
53 *
54 * Possible values are "query", "header", "path" or "cookie".
55 *
56 * @var string
57 */
58 public $in = Generator::UNDEFINED;
59
60 /**
61 * A brief description of the parameter.
62 *
63 * This could contain examples of use.
64 *
65 * CommonMark syntax may be used for rich text representation.
66 *
67 * @var string
68 */
69 public $description = Generator::UNDEFINED;
70
71 /**
72 * Determines whether this parameter is mandatory.
73 *
74 * If the parameter location is "path", this property is required and its value must be true.
75 * Otherwise, the property may be included and its default value is false.
76 *
77 * @var bool
78 */
79 public $required = Generator::UNDEFINED;
80
81 /**
82 * Specifies that a parameter is deprecated and should be transitioned out of usage.
83 *
84 * @var bool
85 */
86 public $deprecated = Generator::UNDEFINED;
87
88 /**
89 * Sets the ability to pass empty-valued parameters.
90 *
91 * This is valid only for query parameters and allows sending a parameter with an empty value.
92 *
93 * Default value is false.
94 *
95 * If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue shall be ignored.
96 *
97 * @var bool
98 */
99 public $allowEmptyValue = Generator::UNDEFINED;
100
101 /**
102 * Describes how the parameter value will be serialized depending on the type of the parameter value.
103 *
104 * Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.
105 *
106 * @var string
107 */
108 public $style = Generator::UNDEFINED;
109
110 /**
111 * 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.
112 *
113 * For other types of parameters this property has no effect.
114 *
115 * When style is form, the default value is true.
116 * For all other styles, the default value is false.
117 *
118 * @var bool
119 */
120 public $explode = Generator::UNDEFINED;
121
122 /**
123 * Determines whether the parameter value should allow reserved characters, as defined by RFC3986 :/?#[]@!$&'()*+,;= to be included without percent-encoding.
124 *
125 * This property only applies to parameters with an in value of query.
126 *
127 * The default value is false.
128 *
129 * @var bool
130 */
131 public $allowReserved = Generator::UNDEFINED;
132
133 /**
134 * The schema defining the type used for the parameter.
135 *
136 * @var Schema
137 */
138 public $schema = Generator::UNDEFINED;
139
140 /**
141 * Example of the media type.
142 *
143 * The example should match the specified schema and encoding properties if present.
144 * The example object is mutually exclusive of the examples object.
145 * Furthermore, if referencing a schema which contains an example, the example value shall override the example provided by the schema.
146 * 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.
147 *
148 * @var mixed
149 */
150 public $example = Generator::UNDEFINED;
151
152 /**
153 * Examples of the parameter.
154 *
155 * Each example should contain a value in the correct format as specified in the parameter encoding.
156 * The examples object is mutually exclusive of the example object.
157 * Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.
158 *
159 * @var array<Examples>
160 */
161 public $examples = Generator::UNDEFINED;
162
163 /**
164 * A map containing the representations for the parameter.
165 *
166 * The key is the media type and the value describes it.
167 * The map must only contain one entry.
168 *
169 * @var array<MediaType>|JsonContent|XmlContent|Attachable
170 */
171 public $content = Generator::UNDEFINED;
172
173 /**
174 * Path-style parameters defined by RFC6570.
175 *
176 * @see [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)
177 *
178 * @var string
179 */
180 public $matrix = Generator::UNDEFINED;
181
182 /**
183 * Label style parameters defined by RFC6570.
184 *
185 * @see [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
186 *
187 * @var string
188 */
189 public $label = Generator::UNDEFINED;
190
191 /**
192 * Form style parameters defined by RFC6570.
193 *
194 * This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
195 *
196 * @see [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8)
197 *
198 * @var mixed
199 */
200 public $form = Generator::UNDEFINED;
201
202 /**
203 * Simple style parameters defined by RFC6570.
204 *
205 * This option replaces collectionFormat with a csv value from OpenAPI 2.0.
206 *
207 * @see [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2)
208 *
209 * @var array
210 */
211 public $simple = Generator::UNDEFINED;
212
213 /**
214 * Space separated array values.
215 *
216 * This option replaces collectionFormat equal to ssv from OpenAPI 2.0.
217 *
218 * @var array
219 */
220 public $spaceDelimited = Generator::UNDEFINED;
221
222 /**
223 * Pipe separated array values.
224 *
225 * This option replaces collectionFormat equal to pipes from OpenAPI 2.0.
226 *
227 * @var array
228 */
229 public $pipeDelimited = Generator::UNDEFINED;
230
231 /**
232 * Provides a simple way of rendering nested objects using form parameters.
233 *
234 * @var mixed
235 */
236 public $deepObject = Generator::UNDEFINED;
237
238 /**
239 * @inheritdoc
240 */
241 public static $_required = ['name', 'in'];
242
243 /**
244 * @inheritdoc
245 */
246 public static $_types = [
247 'name' => 'string',
248 'in' => ['query', 'header', 'path', 'cookie'],
249 'description' => 'string',
250 'style' => ['matrix', 'label', 'form', 'simple', 'spaceDelimited', 'pipeDelimited', 'deepObject'],
251 'required' => 'boolean',
252 ];
253
254 /**
255 * @inheritdoc
256 */
257 public static $_nested = [
258 Schema::class => 'schema',
259 Examples::class => ['examples', 'example'],
260 Attachable::class => ['attachables'],
261 ];
262
263 /**
264 * @inheritdoc
265 */
266 public static $_parents = [
267 Components::class,
268 PathItem::class,
269 Operation::class,
270 Get::class,
271 Post::class,
272 Put::class,
273 Delete::class,
274 Patch::class,
275 Head::class,
276 Options::class,
277 Trace::class,
278 ];
279
280 #[\Override]
281 public function validate(?Analysis $analysis = null, string $version = OpenApi::DEFAULT_VERSION, ?object $context = null): bool
282 {
283 $isValid = parent::validate($analysis, $version, $context);
284
285 if (Generator::isDefault($this->ref)) {
286 if ($this->in === 'body') {
287 if (Generator::isDefault($this->schema)) {
288 $this->_context->logger->warning('Field "schema" is required when ' . $this->identity() . ' is in "' . $this->in . '" in ' . $this->_context);
289 $isValid = false;
290 }
291 }
292 }
293
294 return $isValid;
295 }
296
297 #[\Override]
298 public function identity(?array $properties = []): string
299 {
300 return parent::identity(['name', 'in']);
301 }
302 }