Allow finding child attributes in method args (#1368)

zircote · Jan 4, 2023 · 34aeee1 · 34aeee1
1 parent 62ab286
commit 34aeee1
Show file tree

Hide file tree

Showing 15 changed files with 161 additions and 19 deletions.
diff --git a/Examples/nesting/nesting.yaml b/Examples/nesting/nesting.yaml
@@ -40,21 +40,21 @@ components:
           $ref: '#/components/schemas/AlmostModel'
         -
           properties:
-            actual:
-              type: string
             soClose:
               type: string
+            actual:
+              type: string
     AlmostModel:
       type: object
       allOf:
         -
           $ref: '#/components/schemas/BaseModel'
         -
           properties:
-            almost:
-              type: string
             intermediate:
               type: string
+            almost:
+              type: string
     BaseModel:
       properties:
         base:

diff --git a/Examples/using-links-php81/RepositoriesController.php b/Examples/using-links-php81/RepositoriesController.php
@@ -68,7 +68,8 @@ public function getRepository()
     public function getPullRequestsByRepository(
         #[OAT\PathParameter()] string $username,
         #[OAT\PathParameter()] string $slug,
-        #[OAT\PathParameter()] State $state
+        #[OAT\PathParameter()] State $state,
+        #[OAT\QueryParameter()] ?string $label
     ) {
     }
 
@@ -102,7 +103,7 @@ public function getPullRequestsById()
     )
     ]
     #[OAT\Link(link: 'PullRequestMerge', operationId: 'mergePullRequest', parameters: ['username' => '$response.body#/author/username', 'slug' => '$response.body#/repository/slug', 'pid' => '$response.body#/id'])]
-    public function mergePullRequest()
+    public function mergePullRequest(#[OAT\HeaderParameter(name: 'X-NONCE-ID')] string $nonceId, #[OAT\CookieParameter(name: 'User-Bind-Session')] ?string $bindCookie)
     {
     }
 }
diff --git a/Examples/using-links-php81/using-links-php81.yaml b/Examples/using-links-php81/using-links-php81.yaml
@@ -73,6 +73,12 @@ paths:
           required: true
           schema:
             $ref: '#/components/schemas/State'
+        -
+          name: label
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
         '200':
           description: 'An array of pull request objects'
@@ -136,6 +142,18 @@ paths:
           required: true
           schema:
             type: string
+        -
+          name: X-NONCE-ID
+          in: header
+          required: true
+          schema:
+            type: string
+        -
+          name: User-Bind-Session
+          in: cookie
+          required: false
+          schema:
+            type: string
       responses:
         '204':
           description: 'The PR was successfully merged'

diff --git a/src/Analysers/AttributeAnnotationFactory.php b/src/Analysers/AttributeAnnotationFactory.php
@@ -7,7 +7,6 @@
 namespace OpenApi\Analysers;
 
 use OpenApi\Annotations as OA;
-use OpenApi\Attributes as OAT;
 use OpenApi\Context;
 use OpenApi\Generator;
 
@@ -52,20 +51,24 @@ public function build(\Reflector $reflector, Context $context): array
             if ($reflector instanceof \ReflectionMethod) {
                 // also look at parameter attributes
                 foreach ($reflector->getParameters() as $rp) {
-                    foreach ([OAT\Property::class, OAT\Parameter::class, OAT\PathParameter::class] as $attributeName) {
-                        foreach ($rp->getAttributes($attributeName) as $attribute) {
+                    foreach ([OA\Property::class, OA\Parameter::class, OA\RequestBody::class] as $attributeName) {
+                        foreach ($rp->getAttributes($attributeName, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
                             $instance = $attribute->newInstance();
                             $type = (($rnt = $rp->getType()) && $rnt instanceof \ReflectionNamedType) ? $rnt->getName() : Generator::UNDEFINED;
                             $nullable = $rnt ? $rnt->allowsNull() : true;
 
-                            if ($instance instanceof OAT\Property) {
+                            if ($instance instanceof OA\RequestBody) {
+                                $instance->required = !$nullable;
+                            } elseif ($instance instanceof OA\Property) {
                                 $instance->property = $rp->getName();
                                 if (Generator::isDefault($instance->type)) {
                                     $instance->type = $type;
                                 }
                                 $instance->nullable = $nullable;
                             } else {
-                                $instance->name = $rp->getName();
+                                if (!$instance->name || Generator::isDefault($instance->name)) {
+                                    $instance->name = $rp->getName();
+                                }
                                 $instance->required = !$nullable;
                                 $context = new Context(['nested' => $this], $context);
                                 $context->comment = null;
@@ -78,7 +81,7 @@ public function build(\Reflector $reflector, Context $context): array
 
                 if (($rrt = $reflector->getReturnType()) && $rrt instanceof \ReflectionNamedType) {
                     foreach ($annotations as $annotation) {
-                        if ($annotation instanceof OAT\Property && Generator::isDefault($annotation->type)) {
+                        if ($annotation instanceof OA\Property && Generator::isDefault($annotation->type)) {
                             // pick up simple return types
                             $annotation->type = $rrt->getName();
                         }

diff --git a/src/Annotations/CookieParameter.php b/src/Annotations/CookieParameter.php
@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Annotations;
+
+/**
+ * A `@OA\Request` cookie parameter.
+ *
+ * @Annotation
+ */
+class CookieParameter extends Parameter
+{
+    /**
+     * @inheritdoc
+     */
+    public $in = 'cookie';
+}
diff --git a/src/Annotations/HeaderParameter.php b/src/Annotations/HeaderParameter.php
@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Annotations;
+
+/**
+ * A `@OA\Request` header parameter.
+ *
+ * @Annotation
+ */
+class HeaderParameter extends Parameter
+{
+    /**
+     * @inheritdoc
+     */
+    public $in = 'header';
+}
diff --git a/src/Annotations/QueryParameter.php b/src/Annotations/QueryParameter.php
@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Annotations;
+
+/**
+ * A `@OA\Request` query parameter.
+ *
+ * @Annotation
+ */
+class QueryParameter extends Parameter
+{
+    /**
+     * @inheritdoc
+     */
+    public $in = 'query';
+}
diff --git a/src/Attributes/CookieParameter.php b/src/Attributes/CookieParameter.php
@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Attributes;
+
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)]
+class CookieParameter extends Parameter
+{
+    /**
+     * @inheritdoc
+     */
+    public $in = 'cookie';
+}
diff --git a/src/Attributes/HeaderParameter.php b/src/Attributes/HeaderParameter.php
@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Attributes;
+
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)]
+class HeaderParameter extends Parameter
+{
+    /**
+     * @inheritdoc
+     */
+    public $in = 'header';
+}
diff --git a/src/Attributes/PathParameter.php b/src/Attributes/PathParameter.php
@@ -7,7 +7,15 @@
 namespace OpenApi\Attributes;
 
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)]
-class PathParameter extends \OpenApi\Annotations\PathParameter
+class PathParameter extends Parameter
 {
-    use ParameterTrait;
+    /**
+     * @inheritdoc
+     */
+    public $in = 'path';
+
+    /**
+     * @inheritdoc
+     */
+    public $required = true;
 }
diff --git a/src/Attributes/QueryParameter.php b/src/Attributes/QueryParameter.php
@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Attributes;
+
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)]
+class QueryParameter extends Parameter
+{
+    /**
+     * @inheritdoc
+     */
+    public $in = 'query';
+}
diff --git a/src/Attributes/RequestBody.php b/src/Attributes/RequestBody.php
@@ -7,9 +7,10 @@
 namespace OpenApi\Attributes;
 
 use OpenApi\Generator;
+use OpenApi\Annotations as OA;
 
-#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_PARAMETER)]
-class RequestBody extends \OpenApi\Annotations\RequestBody
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY | \Attribute::TARGET_PARAMETER)]
+class RequestBody extends OA\RequestBody
 {
     /**
      * @param array<MediaType>|JsonContent|XmlContent|Attachable|null $content

diff --git a/src/Serializer.php b/src/Serializer.php
@@ -40,6 +40,9 @@ class Serializer
         OA\Options::class,
         OA\Parameter::class,
         OA\PathParameter::class,
+        OA\QueryParameter::class,
+        OA\CookieParameter::class,
+        OA\HeaderParameter::class,
         OA\Patch::class,
         OA\PathItem::class,
         OA\Post::class,

diff --git a/tests/Annotations/AttributesSyncTest.php b/tests/Annotations/AttributesSyncTest.php
@@ -56,7 +56,7 @@ public function testParameterCompleteness(string $annotation): void
                 }
             }
             // oh, well...
-            if ($attributeRC->isSubclassOf(OA\PathParameter::class)) {
+            if ($attributeRC->isSubclassOf(OA\Parameter::class)) {
                 // not relevant
                 unset($typeMismatch['in']);
                 // uses inheritdoc

diff --git a/tests/Annotations/ValidateRelationsTest.php b/tests/Annotations/ValidateRelationsTest.php
@@ -24,7 +24,7 @@ public function testAncestors($class): void
         foreach ($class::$_parents as $parent) {
             $found = false;
             foreach (array_keys($parent::$_nested) as $nestedClass) {
-                if ($nestedClass === $class) {
+                if ($nestedClass === $class || is_subclass_of($class, $nestedClass)) {
                     $found = true;
                     break;
                 }
@@ -45,7 +45,7 @@ public function testNested($class): void
         foreach (array_keys($class::$_nested) as $nestedClass) {
             $found = false;
             foreach ($nestedClass::$_parents as $parent) {
-                if ($parent === $class) {
+                if ($parent === $class || is_subclass_of($class, $parent)) {
                     $found = true;
                     break;
                 }