| 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 |
} |