Debian Codegraph @

vendor/zircote/swagger-php/src/Annotations/Response.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 * Describes a single response from an API Operation, including design-time,
14 * static links to operations based on the response.
15 *
16 * @see [Response Object](https://spec.openapis.org/oas/v3.1.1.html#response-object)
17 *
18 * @Annotation
19 */
20 class Response extends AbstractAnnotation
21 {
22 /**
23 * The relative or absolute path to a response.
24 *
25 * @see [Reference Object](https://spec.openapis.org/oas/v3.1.1.html#reference-object)
26 *
27 * @var string|class-string|object
28 */
29 public $ref = Generator::UNDEFINED;
30
31 /**
32 * The key into Operations->responses array.
33 *
34 * A HTTP status code or <code>default</code>.
35 *
36 * @var string|int
37 */
38 public $response = Generator::UNDEFINED;
39
40 /**
41 * A short description of the response.
42 *
43 * CommonMark syntax may be used for rich text representation.
44 *
45 * @var string
46 */
47 public $description = Generator::UNDEFINED;
48
49 /**
50 * Maps a header name to its definition.
51 *
52 * RFC7230 states header names are case-insensitive.
53 *
54 * If a response header is defined with the name "Content-Type", it shall be ignored.
55 *
56 * @see [RFC7230](https://tools.ietf.org/html/rfc7230#page-22)
57 *
58 * @var list<Header>
59 */
60 public $headers = Generator::UNDEFINED;
61
62 /**
63 * A map containing descriptions of potential response payloads.
64 *
65 * The key is a media type or media type range and the value describes it.
66 *
67 * For responses that match multiple keys, only the most specific key is applicable;
68 * e.g. <code>text/plain</code> overrides <code>text/*</code>.
69 *
70 * @var MediaType|JsonContent|XmlContent|Attachable|array<MediaType|JsonContent|XmlContent|Attachable>
71 */
72 public $content = Generator::UNDEFINED;
73
74 /**
75 * A map of operations links that can be followed from the response.
76 *
77 * The key of the map is a short name for the link, following the naming constraints of the names for Component
78 * Objects.
79 *
80 * @var list<Link>
81 */
82 public $links = Generator::UNDEFINED;
83
84 /**
85 * @inheritdoc
86 */
87 public static $_types = [
88 'description' => 'string',
89 ];
90
91 /**
92 * @inheritdoc
93 */
94 public static $_nested = [
95 MediaType::class => ['content', 'mediaType'],
96 Header::class => ['headers', 'header'],
97 Link::class => ['links', 'link'],
98 Attachable::class => ['attachables'],
99 ];
100
101 /**
102 * @inheritdoc
103 */
104 public static $_parents = [
105 Components::class,
106 Operation::class,
107 Get::class,
108 Post::class,
109 Put::class,
110 Patch::class,
111 Delete::class,
112 Head::class,
113 Options::class,
114 Trace::class,
115 ];
116
117 #[\Override]
118 public function validate(?Analysis $analysis = null, string $version = OpenApi::DEFAULT_VERSION, ?object $context = null): bool
119 {
120 $isValid = parent::validate($analysis, $version, $context);
121
122 if (Generator::isDefault($this->description) && Generator::isDefault($this->ref)) {
123 $this->_context->logger->warning($this->identity() . ' One of description or ref is required in ' . $this->_context);
124 $isValid = false;
125 }
126
127 return $isValid;
128 }
129 }