Debian Codegraph @

vendor/zircote/swagger-php/src/Annotations/Schema.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 * The definition of input and output data types.
14 *
15 * These types can be objects, but also primitives and arrays.
16 *
17 * This object is based on the [JSON Schema Specification](http://json-schema.org) and uses a predefined subset of it.
18 * On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
19 *
20 * @see [Schema Object](https://spec.openapis.org/oas/v3.1.1.html#schema-object)
21 * @see [JSON Schema](http://json-schema.org/)
22 *
23 * @Annotation
24 */
25 class Schema extends AbstractAnnotation
26 {
27 use JsonSchemaTrait;
28
29 /**
30 * The relative or absolute path to the endpoint.
31 *
32 * @see [Reference Object](https://spec.openapis.org/oas/v3.1.1.html#reference-object)
33 *
34 * @var string|class-string|object
35 */
36 public $ref = Generator::UNDEFINED;
37
38 /**
39 * The key into Components->schemas array.
40 *
41 * @var string
42 */
43 public $schema = Generator::UNDEFINED;
44
45 /**
46 * Can be used to decorate a user interface with information about the data produced by this user interface.
47 *
48 * Preferably short; use <code>description</code> for more details.
49 *
50 * @var string
51 */
52 public $title = Generator::UNDEFINED;
53
54 /**
55 * A description will provide explanation about the purpose of the instance described by this schema.
56 *
57 * @var string
58 */
59 public $description = Generator::UNDEFINED;
60
61 /**
62 * The maximum number of properties allowed in an object instance.
63 * An object instance is valid against this property if its number of properties is less than, or equal to, the
64 * value of this attribute.
65 *
66 * @var int
67 */
68 public $maxProperties = Generator::UNDEFINED;
69
70 /**
71 * The minimum number of properties allowed in an object instance.
72 * An object instance is valid against this property if its number of properties is greater than, or equal to, the
73 * value of this attribute.
74 *
75 * @var int
76 */
77 public $minProperties = Generator::UNDEFINED;
78
79 /**
80 * An object instance is valid against this property if its property set contains all elements in this property's
81 * array value.
82 *
83 * @var list<string>
84 */
85 public $required = Generator::UNDEFINED;
86
87 /**
88 * A collection of properties to define for an object.
89 *
90 * Each property is represented as an instance of the <a href="#property">Property</a> class.
91 *
92 * @var list<Property>
93 */
94 public $properties = Generator::UNDEFINED;
95
96 /**
97 * The type of the schema/property.
98 *
99 * OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".
100 *
101 * Since OpenApi v3.1 an array of types may be used.
102 *
103 * @var string|non-empty-array<string>
104 */
105 public $type = Generator::UNDEFINED;
106
107 /**
108 * The extending format for the previously mentioned type.
109 *
110 * @see [Data Types](https://spec.openapis.org/oas/v3.1.1.html#data-types)
111 *
112 * @var string
113 */
114 public $format = Generator::UNDEFINED;
115
116 /**
117 * Required if type is "array". Describes the type of items in the array.
118 *
119 * @var Items
120 */
121 public $items = Generator::UNDEFINED;
122
123 /**
124 * Determines the format of the array if type array is used.
125 *
126 * Possible values are:
127 * - csv: comma separated values foo,bar.
128 * - ssv: space separated values foo bar.
129 * - tsv: tab separated values foo\tbar.
130 * - pipes: pipe separated values foo|bar.
131 * - multi: corresponds to multiple parameter instances instead of multiple values for a single instance
132 * foo=bar&foo=baz. This is valid only for parameters of type <code>query</code> or <code>formData</code>. Default
133 * value is csv.
134 *
135 * @var string
136 */
137 public $collectionFormat = Generator::UNDEFINED;
138
139 /**
140 * A string instance is considered valid if the regular expression matches the instance successfully.
141 *
142 * @var string
143 */
144 public $pattern = Generator::UNDEFINED;
145
146 /**
147 * A numeric instance is valid against "multipleOf" if the result of the division of the instance by this
148 * property's value is an integer.
149 *
150 * @var int|float
151 */
152 public $multipleOf = Generator::UNDEFINED;
153
154 /**
155 * Adds support for polymorphism.
156 *
157 * The discriminator is an object name that is used to differentiate between other schemas which may satisfy the
158 * payload description. See Composition and Inheritance for more details.
159 *
160 * @var Discriminator
161 */
162 public $discriminator = Generator::UNDEFINED;
163
164 /**
165 * Declares the property as "read only".
166 *
167 * Relevant only for Schema "properties" definitions.
168 *
169 * This means that it may be sent as part of a response but should not be sent as part of the request.
170 * If the property is marked as readOnly being true and is in the required list, the required will take effect on
171 * the response only. A property must not be marked as both readOnly and writeOnly being true. Default value is
172 * false.
173 *
174 * @var bool
175 */
176 public $readOnly = Generator::UNDEFINED;
177
178 /**
179 * Declares the property as "write only".
180 *
181 * Relevant only for Schema "properties" definitions.
182 * Therefore, it may be sent as part of a request but should not be sent as part of the response.
183 * If the property is marked as writeOnly being true and is in the required list, the required will take effect on
184 * the request only. A property must not be marked as both readOnly and writeOnly being true. Default value is
185 * false.
186 *
187 * @var bool
188 */
189 public $writeOnly = Generator::UNDEFINED;
190
191 /**
192 * This may be used only on properties schemas.
193 *
194 * It has no effect on root schemas.
195 * Adds additional metadata to describe the XML representation of this property.
196 *
197 * @var Xml
198 */
199 public $xml = Generator::UNDEFINED;
200
201 /**
202 * Additional external documentation for this schema.
203 *
204 * @var ExternalDocumentation
205 */
206 public $externalDocs = Generator::UNDEFINED;
207
208 /**
209 * A free-form property to include an example of an instance for this schema.
210 *
211 * To represent examples that cannot naturally be represented in JSON or YAML, a string value can be used to
212 * contain the example with escaping where necessary.
213 *
214 * @var mixed
215 */
216 public $example = Generator::UNDEFINED;
217
218 /**
219 * Examples of the schema.
220 *
221 * Each example should contain a value in the correct format as specified in the parameter encoding.
222 * The examples object is mutually exclusive of the example object.
223 * Furthermore, if referencing a schema which contains an example, the examples value shall override the example provided by the schema.
224 *
225 * @since OpenAPI 3.1.0
226 * @var array<Examples>
227 */
228 public $examples = Generator::UNDEFINED;
229
230 /**
231 * Allows sending a null value for the defined schema.
232 * Default value is false.
233 *
234 * This must not be used when using OpenApi version 3.1,
235 * instead make the "type" property an array and add "null" as a possible type.
236 *
237 * @var bool
238 *
239 * @see https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
240 */
241 public $nullable = Generator::UNDEFINED;
242
243 /**
244 * Specifies that a schema is deprecated and should be transitioned out of usage.
245 * Default value is false.
246 *
247 * @var bool
248 */
249 public $deprecated = Generator::UNDEFINED;
250
251 /**
252 * An instance validates successfully against this property if it validates successfully against all schemas
253 * defined by this property's value.
254 *
255 * @var array<Schema|\OpenApi\Attributes\Schema>
256 */
257 public $allOf = Generator::UNDEFINED;
258
259 /**
260 * An instance validates successfully against this property if it validates successfully against at least one
261 * schema defined by this property's value.
262 *
263 * @var array<Schema|\OpenApi\Attributes\Schema>
264 */
265 public $anyOf = Generator::UNDEFINED;
266
267 /**
268 * An instance validates successfully against this property if it validates successfully against exactly one schema
269 * defined by this property's value.
270 *
271 * @var array<Schema|\OpenApi\Attributes\Schema>
272 */
273 public $oneOf = Generator::UNDEFINED;
274
275 /**
276 * https://spec.openapis.org/oas/v3.1.0.html#considerations-for-file-uploads
277 * https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.8.3.
278 *
279 * @var string
280 */
281 public $contentEncoding = Generator::UNDEFINED;
282
283 /**
284 * https://spec.openapis.org/oas/v3.1.0.html#considerations-for-file-uploads
285 * https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.8.4.
286 *
287 * @var string
288 */
289 public $contentMediaType = Generator::UNDEFINED;
290
291 /**
292 * @inheritdoc
293 */
294 public static $_types = [
295 'title' => 'string',
296 'description' => 'string',
297 'required' => '[string]',
298 'format' => 'string',
299 'collectionFormat' => ['csv', 'ssv', 'tsv', 'pipes', 'multi'],
300 'maximum' => 'number',
301 'exclusiveMaximum' => 'boolean|number',
302 'minimum' => 'number',
303 'exclusiveMinimum' => 'boolean|number',
304 'maxLength' => 'integer',
305 'minLength' => 'integer',
306 'pattern' => 'string',
307 'maxItems' => 'integer',
308 'minItems' => 'integer',
309 'uniqueItems' => 'boolean',
310 'multipleOf' => 'integer',
311 'allOf' => '[' . Schema::class . ']',
312 'oneOf' => '[' . Schema::class . ']',
313 'anyOf' => '[' . Schema::class . ']',
314 'contentEncoding' => 'string',
315 'contentMediaType' => 'string',
316 ];
317
318 /**
319 * @inheritdoc
320 */
321 public static $_nested = [
322 Discriminator::class => 'discriminator',
323 Items::class => 'items',
324 Property::class => ['properties', 'property'],
325 ExternalDocumentation::class => 'externalDocs',
326 Examples::class => ['examples', 'example'],
327 Xml::class => 'xml',
328 AdditionalProperties::class => 'additionalProperties',
329 Attachable::class => ['attachables'],
330 ];
331
332 /**
333 * @inheritdoc
334 */
335 public static $_parents = [
336 Components::class,
337 Parameter::class,
338 PathParameter::class,
339 MediaType::class,
340 Header::class,
341 ];
342
343 /**
344 * Type safe nullable check.
345 *
346 * Defaults to `false` when nullable is not set.
347 */
348 public function isNullable(): bool
349 {
350 return !Generator::isDefault($this->nullable) && $this->nullable;
351 }
352
353 /**
354 * Check if the given type is valid for this schema.
355 */
356 public function hasType(string $type): bool
357 {
358 return in_array($type, (array) $this->type, strict: true);
359 }
360
361 public function jsonSerialize(): \stdClass
362 {
363 $data = parent::jsonSerialize();
364
365 if ($this->_context->isVersion('3.0.x')) {
366 unset($data->examples);
367 if (isset($data->const)) {
368 $data->enum = [$data->const];
369 unset($data->const);
370 }
371 }
372
373 return $data;
374 }
375
376 #[\Override]
377 public function validate(?Analysis $analysis = null, string $version = OpenApi::DEFAULT_VERSION, ?object $context = null): bool
378 {
379 $isValid = parent::validate($analysis, $version, $context);
380
381 if ($this->hasType('array') && Generator::isDefault($this->items)) {
382 $this->_context->logger->warning('@OA\\Items() is required when ' . $this->identity() . ' has type "array" in ' . $this->_context);
383
384 $isValid = false;
385 }
386
387 if (OpenApi::versionMatch($version, '3.0.x')) {
388 if (!Generator::isDefault($this->examples)) {
389 $this->_context->logger->warning(static::shorten(static::class) . '::examples is only allowed as of 3.1.0 in ' . $this->_context);
390 $isValid = false;
391 }
392 }
393
394 return $isValid;
395 }
396 }