Add new information to LRD

.github/workflows/phptest.yml

@@ -10,7 +10,7 @@ jobs:
 
     strategy:
       matrix:
-        php: [7.4, 8.0, 8.1, 8.2, 8.3]
+        php: [8.0, 8.1, 8.2, 8.3]
         laravel: ['8.*', '11.*']
         include:
           - php: 8.0
@@ -28,8 +28,6 @@ jobs:
           - php: '8.2'
             laravel: 11.*
         exclude:
-          - laravel: 11.*
-            php: 7.4
           - laravel: 11.*
             php: 8.0
           - laravel: 11.*

README.md

@@ -158,6 +158,38 @@ Example of using it in the controller:
     {
 ```
 
+# Route grouping
+You can add a `@LRDtag` parameter to the description of your controller to group the routes on the dashboard. Endpoint grouping is still done by routes and these tag will only be used as a friendly name for viewing the dashboard.
+@LRDTags is used to generate documentation in OpenAPI format
+Example of using it in the controller:
+
+```php
+    /**
+     * Class DemoController
+     * @package App\Http\Controllers
+     * @LRDtag Demonstration
+     * Demonstration management endpoint
+     */
+     class DemoController extends Controller
+     {
+```
+
+# Endpoint summary and description
+
+The LRD extracts the summary and description of the PHPDoc endpoint from the controller method, this information is rendered as a summary and description of the routes in the LRD dashboard.  
+To extract this information, the standard established by Laravel's PHPDoc is used, where the first line of the PHPDoc is the summary and the rest of the PHPDoc is the description until a tag with @ [PHPDoc documentation ](https://docs.phpdoc.org/3.0/guide/references/phpdoc/basic-syntax.html#:~:text=param%20and%20%40return.-,Summary,-The%20summary%20is).
+Summary and description are used to generate documentation in OpenAPI format
+
+```php
+    /**
+     * Summary of method.
+     * Description of method
+     * @param MyIndexRequest $request
+     */
+    public function index(MyIndexRequest $request): Resource
+    {
+```
+
 # Extra parameters
 
 You define extra parameters using `@LRDparam`.\
@@ -178,6 +210,61 @@ So, the precedence is `Controller method PHPDoc` < `Rules method PHPDoc` < `Rule
     public function index(MyIndexRequest $request): Resource
     {
 ```
+# Rules and field description and example
+To obtain a description of the fields and rules you can add a `fieldDescriptions()` method to your `formRequest` and return an associative array where the key is the name of the field and the value is the description and example of the field.
+This method is not required, if it is not found, the descriptions will not be added.
+The examples are only used for documentation and are not used for sending the request.
+Descriptions and examples are used to generate documentation in OpenAPI format
+```php
+    class UserRequest extends FormRequest
+    {
+    /**
+     * Get the validation rules that apply to the request.
+     */
+    public function rules(): array
+    {
+        return [
+            'name' => 'required|string|max:50',
+            'password' => 'string|min:8|max:100|',
+            'remember' => 'required|boolean|required_if',
+        ];
+    }
+
+    /**
+     * Provides a detailed description of the expected parameters
+     * in the body of an HTTP request.
+     */
+    public function fieldDescriptions(): array
+    {
+        return [
+            'name' => 'Name of user'
+            'password' => 'The password of the user being created',
+            'remember' => 'Whether or not the user should be reminded'
+        ];
+    }
+```
+
+# Rule order
+The order of the rules that will be displayed in the documentation will be changed to the rule registered in the rules method as a way of maintaining the display standard. If not informed, the display rule will be the same as the `rules` method.
+It is recommended that `nullable` be inserted at the end of the rules to correctly present the description `or null`
+
+```php
+    'rules_order' => [
+        'required',
+        'required_if',
+        'file',
+        'integer',
+        'string',
+        'bool',
+        'date',
+        'file',
+        'image',
+        'array',
+        'min',
+        'max',
+        'nullable',
+    ]
+```
 
 # Response codes
 Without explicitly declaring response codes,

composer.json

@@ -20,7 +20,8 @@
         "illuminate/contracts": "^8.37|^9.0|^10.0|^11.0",
         "kitloong/laravel-app-logger": "^1.0",
         "spatie/laravel-package-tools": "^1.4.3",
-        "ext-json": "*"
+        "ext-json": "*",
+        "phpdocumentor/reflection-docblock": "^5.4.1"
     },
     "require-dev": {
         "barryvdh/laravel-ide-helper": "^2.12|dev-master",

config/request-docs.php

@@ -180,5 +180,28 @@
     'exclude_fields' => [
     ],
 
+    // Use factory to create data examples
     'use_factory' => false,
+
+    // Regex to extract the model name from the controller name
+    'pattern_model_from_controller_name' => '/APIController$/',
+
+    // Path where the project's factories are located
+    'factory_path' => 'Database\Factories',
+
+    'rules_order' => [
+        'required',
+        'required_if',
+        'file',
+        'integer',
+        'string',
+        'bool',
+        'date',
+        'file',
+        'image',
+        'array',
+        'min',
+        'max',
+        'nullable',
+    ]
 ];

src/Doc.php

@@ -71,7 +71,7 @@ class Doc implements Arrayable
     private array $rules;
 
     /**
-     * The parsed validation rules.
+     * Examples generated by factories.
      *
      * @var array<string, string[]>
      */
@@ -113,16 +113,57 @@ class Doc implements Arrayable
     private int $groupIndex;
 
     /**
-     * @param  string  $uri
-     * @param  string[]  $methods
-     * @param  string[]  $middlewares
-     * @param  string  $controller
-     * @param  string  $controllerFullPath
-     * @param  string  $method
-     * @param  string  $httpMethod
-     * @param  array<string, string[]>  $rules
-     * @param  string  $docBlock
+     * Description list and examples for fields.
+     *
+     * @var array<string, string[]>
+     */
+    private array $fieldInfo;
+
+    /**
+     * Rules order.
+     *
+     * @var array<string>
+     */
+    private array $rulesOrder;
+
+    /**
+     * Endpoint summary.
+     *
+     * @var string
+     */
+    private string $summary;
+
+    /**
+     * Endpoint description.
+     *
+     * @var string
+     */
+    private string $description;
+
+    /**
+     * Endpoint tag.
+     *
+     * @var string
+     */
+    private string $tag;
+
+    /**
+     * @param string $uri
+     * @param string[] $methods
+     * @param string[] $middlewares
+     * @param string $controller
+     * @param string $controllerFullPath
+     * @param string $method
+     * @param string $httpMethod
+     * @param array $pathParameters
+     * @param array<string, string[]> $rules
+     * @param string $docBlock
      * @param array<string, string[]> $examples
+     * @param array<string, string[]> $fieldInfo
+     * @param array<string> $rulesOrder
+     * @param string $summary
+     * @param string $description
+     * @param string $tag
      */
     public function __construct(
         string $uri,
@@ -136,6 +177,11 @@ public function __construct(
         array $rules,
         string $docBlock,
         array $examples,
+        array $fieldInfo,
+        array $rulesOrder,
+        string $summary,
+        string $description,
+        string $tag
     ) {
         $this->uri                = $uri;
         $this->methods            = $methods;
@@ -148,7 +194,12 @@ public function __construct(
         $this->rules              = $rules;
         $this->docBlock           = $docBlock;
         $this->responses          = [];
-        $this->examples           = $rules;
+        $this->examples           = $examples;
+        $this->fieldInfo          = $fieldInfo;
+        $this->rulesOrder         = $rulesOrder;
+        $this->summary            = $summary;
+        $this->description        = $description;
+        $this->tag                = $tag;
     }
 
     /**
@@ -304,9 +355,9 @@ public function getExamples(): array
     }
 
     /**
-     * @param  array<string, string[]>  $rules
+     * @param array<string, string[]> $examples
      */
-    public function setExamples(array $rules): void
+    public function setExamples(array $examples): void
     {
         $this->examples = $examples;
     }
@@ -375,10 +426,79 @@ public function clone(): Doc
         return clone $this;
     }
 
+    /**
+     * @return array<string, string[]>
+     */
+    public function getFieldInfo(): array
+    {
+        return $this->fieldInfo;
+    }
+
+    /**
+     * @param array<string, string[]> $fieldInfo
+     */
+    public function setFieldInfo(array $fieldInfo): void
+    {
+        foreach ($fieldInfo as $key => $item) {
+            $this->fieldInfo[$key] = [
+                'description' => $item,
+                'example'     => $this->examples[$key] ?? ''
+            ];
+        }
+    }
+
+    /**
+     * @return array<string>
+     */
+    public function getRulesOrder(): array
+    {
+        return $this->rulesOrder;
+    }
+
+    /**
+     * @param array<string> $rulesOrder
+     */
+    public function setRulesOrder(array $rulesOrder): void
+    {
+        $this->rulesOrder = $rulesOrder;
+    }
+
+    public function getSummary(): string
+    {
+        return $this->summary;
+    }
+
+    public function setSummary(string $summary): void
+    {
+        $this->summary = $summary;
+    }
+
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+
+    public function setDescription(string $description): void
+    {
+        $this->description = $description;
+    }
+
+    public function getTag(): string
+    {
+        return $this->tag;
+    }
+
+    public function setTag(string $tag): void
+    {
+        $this->tag = $tag;
+    }
+
     public function toArray(): array
     {
         $result = [
             'uri'                  => $this->uri,
+            'summary'              => $this->summary,
+            'description'          => $this->description,
             'middlewares'          => $this->middlewares,
             'controller'           => $this->controller,
             'controller_full_path' => $this->controllerFullPath,
@@ -389,6 +509,9 @@ public function toArray(): array
             'doc_block'            => $this->docBlock,
             'responses'            => $this->responses,
             'examples'             => $this->examples,
+            'field_info'           => $this->fieldInfo,
+            'rules_order'          => $this->rulesOrder,
+            'tag'                  => $this->tag,
         ];
 
         if (isset($this->group)) {