vendor/zircote/swagger-php/src/Annotations/Response.php line 121

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