Debian Codegraph @

vendor/zircote/swagger-php/src/Annotations/Components.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\Generator;
10
11 /**
12 * Holds a set of reusable objects for different aspects of the OA.
13 *
14 * All objects defined within the components object will have no effect on the API unless they are explicitly
15 * referenced from properties outside the components object.
16 *
17 * @see [Components Object](https://spec.openapis.org/oas/v3.1.1.html#components-object)
18 *
19 * @Annotation
20 */
21 class Components extends AbstractAnnotation
22 {
23 public const COMPONENTS_PREFIX = '#/components/';
24
25 /**
26 * Schema reference.
27 *
28 * @var string
29 */
30 public const SCHEMA_REF = '#/components/schemas/';
31
32 /**
33 * Reusable Schemas.
34 *
35 * @var array<Schema|\OpenApi\Attributes\Schema>
36 */
37 public $schemas = Generator::UNDEFINED;
38
39 /**
40 * Reusable Responses.
41 *
42 * @var list<Response>
43 */
44 public $responses = Generator::UNDEFINED;
45
46 /**
47 * Reusable Parameters.
48 *
49 * @var list<Parameter>
50 */
51 public $parameters = Generator::UNDEFINED;
52
53 /**
54 * Reusable Examples.
55 *
56 * @var array<Examples>
57 */
58 public $examples = Generator::UNDEFINED;
59
60 /**
61 * Reusable Request Bodies.
62 *
63 * @var list<RequestBody>
64 */
65 public $requestBodies = Generator::UNDEFINED;
66
67 /**
68 * Reusable Headers.
69 *
70 * @var list<Header>
71 */
72 public $headers = Generator::UNDEFINED;
73
74 /**
75 * Reusable Security Schemes.
76 *
77 * @var list<SecurityScheme>
78 */
79 public $securitySchemes = Generator::UNDEFINED;
80
81 /**
82 * Reusable Links.
83 *
84 * @var list<Link>
85 */
86 public $links = Generator::UNDEFINED;
87
88 /**
89 * Reusable Callbacks.
90 *
91 * @var array
92 */
93 public $callbacks = Generator::UNDEFINED;
94
95 /**
96 * @inheritdoc
97 */
98 public static $_parents = [
99 OpenApi::class,
100 ];
101
102 /**
103 * @inheritdoc
104 */
105 public static $_nested = [
106 Response::class => ['responses', 'response'],
107 Parameter::class => ['parameters', 'parameter'],
108 PathParameter::class => ['parameters', 'parameter'],
109 RequestBody::class => ['requestBodies', 'request'],
110 Examples::class => ['examples', 'example'],
111 Header::class => ['headers', 'header'],
112 SecurityScheme::class => ['securitySchemes', 'securityScheme'],
113 Link::class => ['links', 'link'],
114 Schema::class => ['schemas', 'schema'],
115 Attachable::class => ['attachables'],
116 ];
117
118 /**
119 * Returns a list of component annotation types.
120 *
121 * Each may be used as a root to resolve component refs
122 */
123 public static function componentTypes(): array
124 {
125 return array_filter(array_keys(self::$_nested), static fn (string $value): bool => $value !== Attachable::class);
126 }
127
128 /**
129 * Generate a <code>#/components/...</code> reference for the given annotation.
130 *
131 * A <code>string</code> component value always assumes type <code>Schema</code>.
132 *
133 * @param AbstractAnnotation|string $component
134 */
135 public static function ref($component, bool $encode = true): string
136 {
137 if ($component instanceof AbstractAnnotation) {
138 foreach (Components::$_nested as $type => $nested) {
139 // exclude attachables
140 if (2 == count($nested)) {
141 if ($component instanceof $type) {
142 $type = $nested[0];
143 $name = $component->{$nested[1]};
144 break;
145 }
146 }
147 }
148 } else {
149 $type = 'schemas';
150 $name = $component;
151 }
152
153 return self::COMPONENTS_PREFIX . $type . '/' . ($encode ? static::refEncode((string) $name) : $name);
154 }
155
156 /**
157 * Escapes the special characters "/" and "~".
158 *
159 * https://swagger.io/docs/specification/using-ref/
160 * https://tools.ietf.org/html/rfc6901#page-3
161 */
162 public static function refEncode(string $raw): string
163 {
164 return str_replace('/', '~1', str_replace('~', '~0', $raw));
165 }
166
167 /**
168 * Converted the escaped characters "~1" and "~" back to "/" and "~".
169 *
170 * https://swagger.io/docs/specification/using-ref/
171 * https://tools.ietf.org/html/rfc6901#page-3
172 */
173 public static function refDecode(string $encoded): string
174 {
175 return str_replace('~1', '/', str_replace('~0', '~', $encoded));
176 }
177 }