Make Response::description optional when $ref is set (#1054)

zircote · Jan 9, 2022 · c5a5320 · c5a5320
1 parent 8d6790d
commit c5a5320
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 10 deletions.
diff --git a/Examples/misc/misc-api.php b/Examples/misc/misc-api.php
@@ -47,7 +47,7 @@ class OpenApiSpec
  *      @OA\Property(property="color", type="string"),
  *   )),
  *   security={{ "bearerAuth":{} }},
- *   @OA\Response(response="200",ref="#/components/responses/200", description="Success")
+ *   @OA\Response(response="200", ref="#/components/responses/200")
  * )
  */
 class Endpoint
@@ -57,7 +57,7 @@ class Endpoint
 /**
  * @OA\Response(
  *     response=200,
- *     description="",
+ *     description="Success",
  *     @OA\MediaType(
  *          mediaType="application/json",
  *          @OA\Schema(

diff --git a/Examples/misc/misc.yaml b/Examples/misc/misc.yaml
@@ -37,7 +37,7 @@ paths:
 components:
   responses:
     '200':
-      description: ''
+      description: Success
       content:
         application/json:
           schema:

diff --git a/src/Annotations/License.php b/src/Annotations/License.php
@@ -92,7 +92,7 @@ public function validate(array $parents = [], array $skip = [], string $ref = ''
 
         if ($this->_context->isVersion(OpenApi::VERSION_3_1_0)) {
             if ($this->url !== Generator::UNDEFINED && $this->identifier !== Generator::UNDEFINED) {
-                $this->_context->logger->warning('@OA\\License() url and identifier are mutually exclusive');
+                $this->_context->logger->warning($this->identity() . ' url and identifier are mutually exclusive');
                 $valid = false;
             }
         }

diff --git a/src/Annotations/Response.php b/src/Annotations/Response.php
@@ -28,7 +28,7 @@ class Response extends AbstractAnnotation
     /**
      * The key into Operations->responses array.
      *
-     * @var string a HTTP Status Code or "default"
+     * @var string|int a HTTP Status Code or "default"
      */
     public $response = Generator::UNDEFINED;
 
@@ -68,11 +68,6 @@ class Response extends AbstractAnnotation
      */
     public $links = Generator::UNDEFINED;
 
-    /**
-     * @inheritdoc
-     */
-    public static $_required = ['description'];
-
     /**
      * @inheritdoc
      */
@@ -105,4 +100,19 @@ class Response extends AbstractAnnotation
         Options::class,
         Trace::class,
     ];
+
+    /**
+     * @inheritdoc
+     */
+    public function validate(array $parents = [], array $skip = [], string $ref = ''): bool
+    {
+        $valid = parent::validate($parents, $skip);
+
+        if ($this->description === Generator::UNDEFINED && $this->ref === Generator::UNDEFINED) {
+            $this->_context->logger->warning($this->identity() . ' One of description or ref is required');
+            $valid = false;
+        }
+
+        return $valid;
+    }
 }