Debian Codegraph @

vendor/zircote/swagger-php/src/Processors/AugmentParameters.php

raw
1 <?php declare(strict_types=1);
2
3 /**
4 * @license Apache 2.0
5 */
6
7 namespace OpenApi\Processors;
8
9 use OpenApi\Analysis;
10 use OpenApi\Annotations as OA;
11 use OpenApi\Context;
12 use OpenApi\Generator;
13 use OpenApi\GeneratorAwareInterface;
14 use OpenApi\GeneratorAwareTrait;
15 use OpenApi\Processors\Concerns\DocblockTrait;
16
17 /**
18 * Augments shared and operations parameters from docblock comments.
19 */
20 class AugmentParameters implements GeneratorAwareInterface
21 {
22 use DocblockTrait;
23
24 use GeneratorAwareTrait;
25
26 protected bool $augmentOperationParameters;
27
28 public function __construct(bool $augmentOperationParameters = true)
29 {
30 $this->augmentOperationParameters = $augmentOperationParameters;
31 }
32
33 public function isAugmentOperationParameters(): bool
34 {
35 return $this->augmentOperationParameters;
36 }
37
38 /**
39 * If set to <code>true</code> try to find operation parameter descriptions in the operation docblock.
40 */
41 public function setAugmentOperationParameters(bool $augmentOperationParameters): AugmentParameters
42 {
43 $this->augmentOperationParameters = $augmentOperationParameters;
44
45 return $this;
46 }
47
48 public function __invoke(Analysis $analysis): void
49 {
50 $this->augmentParameters($analysis);
51 $this->augmentSharedParameters($analysis);
52 if ($this->augmentOperationParameters) {
53 $this->augmentOperationParameters($analysis);
54 }
55 }
56
57 protected function augmentParameters(Analysis $analysis): void
58 {
59 $parameters = $analysis->getAnnotationsOfType(OA\Parameter::class);
60
61 foreach ($parameters as $parameter) {
62 $context = $parameter->_context;
63
64 if (Generator::isDefault($parameter->name) && null !== $context->reflector && method_exists($context->reflector, 'getName')) {
65 $parameter->name = $context->reflector->getName();
66 }
67
68 if ($context->reflector instanceof \ReflectionParameter) {
69 $schema = Generator::isDefault($parameter->schema)
70 ? new OA\Schema([
71 '_context' => new Context([
72 'generated' => true,
73 'reflector' => $context->reflector,
74 ], $context),
75 ])
76 : $parameter->schema;
77
78 $this->generator->getTypeResolver()->augmentSchemaType($analysis, $schema);
79
80 $analysis->mergeAnnotations($parameter, [new OA\Schema([
81 'type' => $schema->type,
82 'format' => $schema->format,
83 'items' => $schema->items,
84 'oneOf' => $schema->oneOf,
85 'allOf' => $schema->allOf,
86 'anyOf' => $schema->anyOf,
87 'ref' => $schema->ref,
88 '_context' => new Context([
89 'nested' => null,
90 'comment' => null,
91 'reflector' => $context->reflector,
92 ], $context)]),
93 ]);
94
95 if (Generator::isDefault($parameter->required)) {
96 $parameter->required = !$schema->isNullable();
97 }
98 }
99
100 if (!Generator::isDefault($parameter->schema)) {
101 $this->generator->getTypeResolver()->mapNativeType($parameter->schema, $parameter->schema->type);
102 }
103 }
104 }
105
106 /**
107 * Use the parameter->name as key field (parameter->parameter) when used as reusable component
108 * (openapi->components->parameters).
109 */
110 protected function augmentSharedParameters(Analysis $analysis): void
111 {
112 if (!Generator::isDefault($analysis->openapi->components) && !Generator::isDefault($analysis->openapi->components->parameters)) {
113 $keys = [];
114 $parametersWithoutKey = [];
115 foreach ($analysis->openapi->components->parameters as $parameter) {
116 if (!Generator::isDefault($parameter->parameter) && $parameter->parameter !== null) {
117 $keys[$parameter->parameter] = $parameter;
118 } else {
119 $parametersWithoutKey[] = $parameter;
120 }
121 }
122 foreach ($parametersWithoutKey as $parameter) {
123 if (!Generator::isDefault($parameter->name) && $parameter->name !== null && empty($keys[$parameter->name])) {
124 $parameter->parameter = $parameter->name;
125 $keys[$parameter->parameter] = $parameter;
126 }
127 }
128 }
129 }
130
131 protected function augmentOperationParameters(Analysis $analysis): void
132 {
133 $operations = $analysis->getAnnotationsOfType(OA\Operation::class);
134
135 foreach ($operations as $operation) {
136 if (!Generator::isDefault($operation->parameters)) {
137 $tags = [];
138 $this->parseDocblock($operation->_context->comment, $tags);
139 $operationDocblockParams = $tags['param'] ?? [];
140
141 foreach ($operation->parameters as $parameter) {
142 if (Generator::isDefault($parameter->description)) {
143 $typeAndDescription = $this->parseVarLine((string) $parameter->_context->comment);
144 if ($typeAndDescription['description']) {
145 $parameter->description = trim($typeAndDescription['description']);
146 }
147 }
148
149 if (Generator::isDefault($parameter->description)) {
150 if (array_key_exists($parameter->name, $operationDocblockParams)) {
151 $details = $operationDocblockParams[$parameter->name];
152 if ($details['description']) {
153 $parameter->description = $details['description'];
154 }
155 }
156 } elseif (null === $parameter->description) {
157 $parameter->description = Generator::UNDEFINED;
158 }
159 }
160 }
161 }
162 }
163 }