Debian Codegraph @

vendor/zircote/swagger-php/src/Processors/DocBlockDescriptions.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\Generator;
12
13 /**
14 * Checks if the annotation has a summary and/or description property
15 * and uses the text in the comment block (above the annotations) as summary and/or description.
16 *
17 * Use <code>null</code>, for example <code>@Annotation(description=null)</code>,
18 * if you don't want the annotation to have a description.
19 */
20 class DocBlockDescriptions
21 {
22 use Concerns\DocblockTrait;
23
24 public function __invoke(Analysis $analysis): void
25 {
26 /** @var OA\AbstractAnnotation $annotation */
27 foreach ($analysis->annotations as $annotation) {
28 if (property_exists($annotation, '_context') === false) {
29 // only annotations with context
30 continue;
31 }
32
33 if (!$this->isDocblockRoot($annotation)) {
34 // only top-level annotations
35 continue;
36 }
37
38 if ($annotation instanceof OA\Parameter || $annotation instanceof OA\Property) {
39 // they have their dedicated processor
40 continue;
41 }
42
43 $hasSummary = property_exists($annotation, 'summary');
44 $hasDescription = property_exists($annotation, 'description');
45 if (!$hasSummary && !$hasDescription) {
46 continue;
47 }
48
49 if ($hasSummary && $hasDescription) {
50 $this->summaryAndDescription($annotation);
51 } elseif ($hasDescription) {
52 $this->description($annotation);
53 }
54 }
55 }
56
57 /**
58 * @param OA\Operation|OA\Property|OA\Parameter|OA\Schema $annotation
59 */
60 protected function description(OA\AbstractAnnotation $annotation): void
61 {
62 if (!Generator::isDefault($annotation->description)) {
63 if ($annotation->description === null) {
64 $annotation->description = Generator::UNDEFINED;
65 }
66
67 return;
68 }
69
70 $annotation->description = $this->parseDocblock($annotation->_context->comment);
71 }
72
73 /**
74 * @param OA\Operation|OA\Property|OA\Parameter|OA\Schema $annotation
75 */
76 protected function summaryAndDescription(OA\AbstractAnnotation $annotation): void
77 {
78 $ignoreSummary = !Generator::isDefault($annotation->summary);
79 $ignoreDescription = !Generator::isDefault($annotation->description);
80
81 if ($annotation->summary === null) {
82 $ignoreSummary = true;
83 $annotation->summary = Generator::UNDEFINED;
84 }
85
86 if ($annotation->description === null) {
87 $annotation->description = Generator::UNDEFINED;
88 $ignoreDescription = true;
89 }
90
91 if ($ignoreSummary && $ignoreDescription) {
92 return;
93 }
94
95 $content = $this->parseDocblock($annotation->_context->comment);
96 if ($ignoreSummary) {
97 $annotation->description = $content;
98 } elseif ($ignoreDescription) {
99 $annotation->summary = $content;
100 } else {
101 $annotation->summary = $this->extractCommentSummary($content);
102 $annotation->description = $this->extractCommentDescription($content);
103 }
104 }
105 }