vendor/zircote/swagger-php/src/Annotations/Operation.php line 216

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.  * Base class for `@OA\Get`,  `@OA\Post`,  `@OA\Put`,  etc.
  13.  *
  14.  * Describes a single API operation on a path.
  15.  *
  16.  * @see [OAI Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operation-object)
  17.  *
  18.  * @Annotation
  19.  */
  20. abstract class Operation extends AbstractAnnotation
  21. {
  22.     /**
  23.      * Key in the OpenApi "Paths Object" for this operation.
  24.      *
  25.      * @var string
  26.      */
  27.     public $path = Generator::UNDEFINED;
  29.     /**
  30.      * A list of tags for API documentation control.
  31.      *
  32.      * Tags can be used for logical grouping of operations by resources or any other qualifier.
  33.      *
  34.      * @var string[]
  35.      */
  36.     public $tags = Generator::UNDEFINED;
  38.     /**
  39.      * Key in the OpenApi "Path Item Object" for this operation.
  40.      *
  41.      * Allowed values: 'get', 'post', put', 'patch', 'delete', 'options', 'head' and 'trace'.
  42.      *
  43.      * @var string
  44.      */
  45.     public $method = Generator::UNDEFINED;
  47.     /**
  48.      * A short summary of what the operation does.
  49.      *
  50.      * @var string
  51.      */
  52.     public $summary = Generator::UNDEFINED;
  54.     /**
  55.      * A verbose explanation of the operation behavior.
  56.      *
  57.      * CommonMark syntax MAY be used for rich text representation.
  58.      *
  59.      * @var string
  60.      */
  61.     public $description = Generator::UNDEFINED;
  63.     /**
  64.      * Additional external documentation for this operation.
  65.      *
  66.      * @var ExternalDocumentation
  67.      */
  68.     public $externalDocs = Generator::UNDEFINED;
  70.     /**
  71.      * Unique string used to identify the operation.
  72.      *
  73.      * The id must be unique among all operations described in the API.
  74.      * Tools and libraries may use the operationId to uniquely identify an operation, therefore, it is recommended to
  75.      * follow common programming naming conventions.
  76.      *
  77.      * @var string
  78.      */
  79.     public $operationId = Generator::UNDEFINED;
  81.     /**
  82.      * A list of parameters that are applicable for this operation.
  83.      *
  84.      * If a parameter is already defined at the Path Item, the new definition will override it but can never remove it.
  85.      * The list must not include duplicated parameters.
  86.      *
  87.      * A unique parameter is defined by a combination of a name and location.
  88.      *
  89.      * The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object's
  90.      * components/parameters.
  91.      *
  92.      * @var Parameter[]
  93.      */
  94.     public $parameters = Generator::UNDEFINED;
  96.     /**
  97.      * The request body applicable for this operation.
  98.      *
  99.      * The requestBody is only supported in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly
  100.      * defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody shall be ignored
  101.      * by consumers.
  102.      *
  103.      * @var RequestBody
  104.      */
  105.     public $requestBody = Generator::UNDEFINED;
  107.     /**
  108.      * The list of possible responses as they are returned from executing this operation.
  109.      *
  110.      * @var Response[]
  111.      */
  112.     public $responses = Generator::UNDEFINED;
  114.     /**
  115.      * A map of possible out-of band callbacks related to the parent operation.
  116.      *
  117.      * The key is a unique identifier for the Callback Object.
  118.      *
  119.      * Each value in the map is a Callback Object that describes a request that may be initiated by the API provider
  120.      * and the expected responses. The key value used to identify the callback object is an expression, evaluated at
  121.      * runtime, that identifies a URL to use for the callback operation.
  122.      *
  123.      * @var array
  124.      */
  125.     public $callbacks = Generator::UNDEFINED;
  127.     /**
  128.      * Declares this operation to be deprecated.
  129.      *
  130.      * Consumers should refrain from usage of the declared operation.
  131.      *
  132.      * Default value is false.
  133.      *
  134.      * @var bool
  135.      */
  136.     public $deprecated = Generator::UNDEFINED;
  138.     /**
  139.      * A declaration of which security mechanisms can be used for this operation.
  140.      *
  141.      * The list of values includes alternative security requirement objects that can be used.
  142.      *
  143.      * Only one of the security requirement objects need to be satisfied to authorize a request.
  144.      *
  145.      * This definition overrides any declared top-level security.
  146.      * To remove a top-level security declaration, an empty array can be used.
  147.      *
  148.      * @var array
  149.      */
  150.     public $security = Generator::UNDEFINED;
  152.     /**
  153.      * An alternative server array to service this operation.
  154.      *
  155.      * If an alternative server object is specified at the Path Item Object or Root level, it will be overridden by
  156.      * this value.
  157.      *
  158.      * @var Server[]
  159.      */
  160.     public $servers = Generator::UNDEFINED;
  162.     /**
  163.      * @inheritdoc
  164.      */
  165.     public static $_required = ['responses'];
  167.     /**
  168.      * @inheritdoc
  169.      */
  170.     public static $_types = [
  171.         'path' => 'string',
  172.         'method' => 'string',
  173.         'tags' => '[string]',
  174.         'summary' => 'string',
  175.         'description' => 'string',
  176.         'deprecated' => 'boolean',
  177.     ];
  179.     /**
  180.      * @inheritdoc
  181.      */
  182.     public static $_nested = [
  183.         Parameter::class => ['parameters'],
  184.         PathParameter::class => ['parameters'],
  185.         Response::class => ['responses', 'response'],
  186.         ExternalDocumentation::class => 'externalDocs',
  187.         Server::class => ['servers'],
  188.         RequestBody::class => 'requestBody',
  189.         Attachable::class => ['attachables'],
  190.     ];
  192.     /**
  193.      * @inheritdoc
  194.      */
  195.     #[\ReturnTypeWillChange]
  196.     public function jsonSerialize()
  197.     {
  198.         $data = parent::jsonSerialize();
  200.         unset($data->method);
  201.         unset($data->path);
  203.         // ensure security elements are object
  204.         if (isset($data->security) && is_array($data->security)) {
  205.             foreach ($data->security as $key => $scheme) {
  206.                 $data->security[$key] = (object) $scheme;
  207.             }
  208.         }
  210.         return $data;
  211.     }
  213.     /**
  214.      * @inheritdoc
  215.      */
  216.     public function validate(array $stack = [], array $skip = [], string $ref = '', $context = null): bool
  217.     {
  218.         if (in_array($this, $skip, true)) {
  219.             return true;
  220.         }
  222.         $valid = parent::validate($stack, $skip, $ref, $context);
  224.         if (!Generator::isDefault($this->responses)) {
  225.             foreach ($this->responses as $response) {
  226.                 if (!Generator::isDefault($response->response) && $response->response !== 'default' && preg_match('/^([12345]{1}[0-9]{2})|([12345]{1}XX)$/', (string) $response->response) === 0) {
  227.                     $this->_context->logger->warning('Invalid value "' . $response->response . '" for ' . $response->_identity([]) . '->response, expecting "default", a HTTP Status Code or HTTP Status Code range definition in ' . $response->_context);
  228.                     $valid = false;
  229.                 }
  230.             }
  231.         }
  233.         if (is_object($context) && !Generator::isDefault($this->operationId)) {
  234.             if (!property_exists($context, 'operationIds')) {
  235.                 $context->operationIds = [];
  236.             }
  238.             if (in_array($this->operationId, $context->operationIds)) {
  239.                 $this->_context->logger->warning('operationId must be unique. Duplicate value found: "' . $this->operationId . '"');
  240.                 $valid = false;
  241.             }
  243.             $context->operationIds[] = $this->operationId;
  244.         }
  246.         return $valid;
  247.     }
  248. }