Merge pull request #314 from Ken-vdE/comments-on-rules-method

Allow comments on the rules method of the Request class

Author: kevincobain2000

src/LaravelRequestDocs.php

@@ -231,14 +231,17 @@ public function appendRequestRules(Collection $docs): Collection
                 continue;
             }
 
-            $reflectionMethod = new ReflectionMethod($doc->getControllerFullPath(), $doc->getMethod());
+            $controllerReflectionMethod = new ReflectionMethod($doc->getControllerFullPath(), $doc->getMethod());
 
-            $docComment = $this->getDocComment($reflectionMethod);
+            $controllerMethodDocComment = $this->getDocComment($controllerReflectionMethod);
 
-            $customRules = $this->customParamsDocComment($docComment);
-            $doc->setResponses($this->customResponsesDocComment($docComment));
+            $controllerMethodLrdComment = $this->lrdDocComment($controllerMethodDocComment);
+            $controllerMethodDocRules   = $this->customParamsDocComment($controllerMethodDocComment);
 
-            foreach ($reflectionMethod->getParameters() as $param) {
+            $doc->setResponses($this->customResponsesDocComment($controllerMethodDocComment));
+
+            $lrdDocComments = [];
+            foreach ($controllerReflectionMethod->getParameters() as $param) {
                 /** @var \ReflectionNamedType|\ReflectionUnionType|\ReflectionIntersectionType|null $namedType */
                 $namedType = $param->getType();
                 if (!$namedType) {
@@ -261,18 +264,29 @@ public function appendRequestRules(Collection $docs): Collection
 
                         try {
                             $doc->mergeRules($this->flattenRules($requestObject->$requestMethod()));
+                            $requestReflectionMethod = new ReflectionMethod($requestObject, $requestMethod);
                         } catch (Throwable $e) {
                             $doc->mergeRules($this->rulesByRegex($requestClassName, $requestMethod));
+                            $requestReflectionMethod = new ReflectionMethod($requestClassName, $requestMethod);
                         }
+
+                        $requestMethodDocComment = $this->getDocComment($requestReflectionMethod);
+
+                        $requestMethodLrdComment = $this->lrdDocComment($requestMethodDocComment);
+                        $requestMethodDocRules   = $this->customParamsDocComment($requestMethodDocComment);
+
+                        $lrdDocComments[] = $requestMethodLrdComment;
+                        $doc->mergeRules($requestMethodDocRules);
                     }
                 } catch (Throwable $e) {
                     // Do nothing.
                 }
-
-                $doc->mergeRules($customRules);
             }
 
-            $doc->setDocBlock($this->lrdDocComment($docComment));
+            $lrdDocComments[] = $controllerMethodLrdComment;
+            $lrdDocComments   = array_filter($lrdDocComments, fn($s) => $s !== '');
+            $doc->setDocBlock(join("\n", $lrdDocComments));
+            $doc->mergeRules($controllerMethodDocRules);
         }
         return $docs;
     }

tests/Controllers/LaravelRequestDocsControllerTest.php

@@ -27,7 +27,7 @@ public function testApi()
         );
 
         /** {@see \Rakutentech\LaravelRequestDocs\Tests\TestCase::registerRoutes()} */
-        $this->assertCount(28, $response->json());
+        $this->assertCount(29, $response->json());
 
         $this->assertSame($expected, $response->json());
     }

tests/Stubs/TestControllers/CommentsOnRequestRulesMethodController.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rakutentech\LaravelRequestDocs\Tests\Stubs\TestControllers;
+
+use Rakutentech\LaravelRequestDocs\Tests\Stubs\TestRequests\CommentsOnRequestRulesMethodRequest;
+
+class CommentsOnRequestRulesMethodController
+{
+    /**
+     * Before
+     *
+     * @lrd:start
+     * # Controller
+     * ## Index Method Comment
+     * @lrd:end
+     *
+     * @LRDparam extra_index_field_1 string|max:32
+     * // either space or pipe
+     * @LRDparam extra_index_field_2 string|nullable|max:32
+     * // duplicate param in controller
+     * @LRDparam this_is_a_duplicate_param controller description
+     * // override the default response codes
+     * @LRDresponses 201|244
+     *
+     * After
+     */
+    public function index(CommentsOnRequestRulesMethodRequest $request)
+    {
+        return 1;
+    }
+}

tests/Stubs/TestRequests/CommentsOnRequestRulesMethodRequest.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rakutentech\LaravelRequestDocs\Tests\Stubs\TestRequests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class CommentsOnRequestRulesMethodRequest extends FormRequest
+{
+    /**
+     * Get the validation rules that apply to the request.
+     *
+     * @lrd:start
+     * # Request
+     * ## Rules Method Comment
+     * @lrd:end
+     *
+     * @LRDparam extra_rules_field_1 string|max:32
+     *  // either space or pipe
+     * @LRDparam extra_rules_field_2 string|nullable|max:32
+     *  // duplicate param in controller
+     * @LRDparam this_is_a_duplicate_param request description
+     *
+     * @return array
+     */
+    public function rules()
+    {
+        return [
+            'message_param' => 'nullable|string',
+        ];
+    }
+}

tests/TestCase.php

@@ -43,6 +43,7 @@ public function registerRoutes()
         Route::get('health', [TestControllers\WelcomeController::class, 'health']);
         Route::get('single', TestControllers\SingleActionController::class);
         Route::delete('welcome/no-rules', [TestControllers\WelcomeController::class, 'noRules']);
+        Route::post('comments-on-request-rules-method', [TestControllers\CommentsOnRequestRulesMethodController::class, 'index']);
 
         Route::get('closure', function () {
             return true;

tests/mocks/lrd-response.json

@@ -456,6 +456,47 @@
             "503"
         ]
     },
+    {
+        "uri": "comments-on-request-rules-method",
+        "middlewares": [],
+        "controller": "CommentsOnRequestRulesMethodController",
+        "controller_full_path": "Rakutentech\\LaravelRequestDocs\\Tests\\Stubs\\TestControllers\\CommentsOnRequestRulesMethodController",
+        "method": "index",
+        "http_method": "POST",
+        "path_parameters": [],
+        "rules": {
+            "message_param": [
+                "nullable|string"
+            ],
+            "extra_rules_field_1": [
+                "string",
+                "max:32"
+            ],
+            "extra_rules_field_2": [
+                "string",
+                "nullable",
+                "max:32"
+            ],
+            "this_is_a_duplicate_param": [
+                "controller",
+                "description"
+            ],
+            "extra_index_field_1": [
+                "string",
+                "max:32"
+            ],
+            "extra_index_field_2": [
+                "string",
+                "nullable",
+                "max:32"
+            ]
+        },
+        "doc_block": " # Request\n ## Rules Method Comment\n\n # Controller\n ## Index Method Comment\n",
+        "responses": [
+            "201",
+            "244"
+        ]
+    },
     {
         "uri": "closure",
         "middlewares": [],
@@ -743,4 +784,4 @@
             "503"
         ]
     }
-]
+]