From 532e0daa4f1b13818bbca3134d6e06c5fb90f780 Mon Sep 17 00:00:00 2001
From: Roman Lytvynenko <litvinenko95@gmail.com>
Date: Sun, 7 Apr 2024 12:04:56 +0300
Subject: [PATCH] @query and @default tags support

---
 src/Support/Helpers/ExamplesExtractor.php     |  2 +-
 .../RequestParametersBuilder.php              | 23 ++++++++++++------
 .../RequestBodyExtensionTest.php              | 24 +++++++++++++++++++
 3 files changed, 41 insertions(+), 8 deletions(-)

diff --git a/src/Support/Helpers/ExamplesExtractor.php b/src/Support/Helpers/ExamplesExtractor.php
index de840eb6..ecfa67fb 100644
--- a/src/Support/Helpers/ExamplesExtractor.php
+++ b/src/Support/Helpers/ExamplesExtractor.php
@@ -23,7 +23,7 @@ public static function make(?PhpDocNode $docNode, string $tagName = '@example')
 
     public function extract(bool $preferString = false)
     {
-        if (! count($examples = $this->docNode->getTagsByName($this->tagName))) {
+        if (! count($examples = $this->docNode?->getTagsByName($this->tagName) ?? [])) {
             return [];
         }
 
diff --git a/src/Support/IndexBuilders/RequestParametersBuilder.php b/src/Support/IndexBuilders/RequestParametersBuilder.php
index 240252e4..2066541b 100644
--- a/src/Support/IndexBuilders/RequestParametersBuilder.php
+++ b/src/Support/IndexBuilders/RequestParametersBuilder.php
@@ -81,6 +81,8 @@ public function afterAnalyzedNode(Scope $scope, Node $node)
             $parameterDefault = $parameterDefaultFromDoc;
         }
 
+        $this->checkExplicitParameterPlacementInQuery($node, $parameter);
+
         $parameter
             ->description($this->makeDescriptionFromComments($node))
             ->setSchema(Schema::fromType(
@@ -168,10 +170,7 @@ private function makeDescriptionFromComments(Node\Stmt\Expression $node)
          * @todo: consider adding only @param annotation support,
          * so when description is taken only if comment is marked with @param
          */
-        if ($node->getDocComment()) {
-            /** @var PhpDocNode $phpDoc */
-            $phpDoc = $node->getAttribute('parsedPhpDoc');
-
+        if ($phpDoc = $node->getAttribute('parsedPhpDoc')) {
             return trim($phpDoc->getAttribute('summary').' '.$phpDoc->getAttribute('description'));
         }
 
@@ -188,17 +187,27 @@ private function makeDescriptionFromComments(Node\Stmt\Expression $node)
 
     private function shouldIgnoreParameter(Node\Stmt\Expression $node)
     {
-        /** @var PhpDocNode $phpDoc */
+        /** @var PhpDocNode|null $phpDoc */
         $phpDoc = $node->getAttribute('parsedPhpDoc');
 
-        return !! $phpDoc->getTagsByName('@ignoreParam');
+        return !! $phpDoc?->getTagsByName('@ignoreParam');
     }
 
     private function getParameterDefaultFromPhpDoc(Node\Stmt\Expression $node)
     {
-        /** @var PhpDocNode $phpDoc */
+        /** @var PhpDocNode|null $phpDoc */
         $phpDoc = $node->getAttribute('parsedPhpDoc');
 
         return ExamplesExtractor::make($phpDoc, '@default')->extract()[0] ?? null;
     }
+
+    private function checkExplicitParameterPlacementInQuery(Node\Stmt\Expression $node, Parameter $parameter)
+    {
+        /** @var PhpDocNode|null $phpDoc */
+        $phpDoc = $node->getAttribute('parsedPhpDoc');
+
+        if(!! $phpDoc?->getTagsByName('@query')) {
+            $parameter->setAttribute('isInQuery', true);
+        }
+    }
 }
diff --git a/tests/Support/OperationExtensions/RequestBodyExtensionTest.php b/tests/Support/OperationExtensions/RequestBodyExtensionTest.php
index 3f233c64..98516e82 100644
--- a/tests/Support/OperationExtensions/RequestBodyExtensionTest.php
+++ b/tests/Support/OperationExtensions/RequestBodyExtensionTest.php
@@ -221,3 +221,27 @@ public function index(Illuminate\Http\Request $request)
         $request->integer('foo', 10);
     }
 }
+
+it('allows explicitly specifying parameter placement in query manually in doc', function () {
+    $openApiDocument = generateForRoute(function () {
+        return RouteFacade::post('api/test', [RequestBodyExtensionTest__allows_explicitly_specifying_parameter_placement_in_query_manually_in_doc::class, 'index']);
+    });
+
+    expect($openApiDocument['paths']['/test']['post']['requestBody']['content']['application/json']['schema']['properties'] ?? [])
+        ->toBeEmpty()
+        ->and($openApiDocument['paths']['/test']['post']['parameters'])
+        ->toBe([[
+            'name' => 'foo',
+            'in' => 'query',
+            'schema' => ['type' => 'integer'],
+            'default' => 10,
+        ]]);
+});
+class RequestBodyExtensionTest__allows_explicitly_specifying_parameter_placement_in_query_manually_in_doc
+{
+    public function index(Illuminate\Http\Request $request)
+    {
+        /** @query */
+        $request->integer('foo', 10);
+    }
+}