(v2.1) added responses and LRDresponses

Author: kevincobain2000

README.md

@@ -58,6 +58,7 @@ You can publish the config file with:
 
 ```bash
 php artisan vendor:publish --tag=request-docs-config
+php artisan route:cache
 ```
 
 # Usage
@@ -111,7 +112,7 @@ Example of using it in controller
     /**
      * @lrd:start
      * Hello markdown
-     * ## Free text to write documentation in markdown
+     * Free `code` or *text* to write documentation in markdown
      * @lrd:end
      */
     public function index(MyIndexRequest $request): Resource
@@ -125,7 +126,10 @@ You write extra params with rules with @LRDparam in comment line as one line
 ```php
     /**
      * @LRDparam username string|max:32
+     * // either space or pipe
      * @LRDparam nickaname string|nullable|max:32
+     * // override the default response codes
+     * @LRDparam responses 200,422
      */
     public function index(MyIndexRequest $request): Resource
     {
@@ -175,6 +179,6 @@ Fixing lints
 - v1.23 Bug fix for lrd doc block #76
 - v1.27 A few fixes on width and added request_methods
 - v2.0 UI Renewal to React static
-    - @QAParam is now @LRDparam
+    - `@QAParam` is now `@LRDparam`
     - No special changes for users, upgrade to v2.x as usual
 

config/request-docs.php

@@ -34,6 +34,8 @@
     'rules_methods' => [
         'rules'
     ],
+    // Can be overridden as // @LRDResponses 200|400|401
+    'default_responses' => [ 200, 400, 401, 403, 404, 405, 422, 429, 500, 503],
 
     // No need to touch below
     // open api config

src/LaravelRequestDocs.php

@@ -193,7 +193,10 @@ public function appendRequestRules(array $controllersInfo): array
                 continue;
             }
             $params           = $reflectionMethod->getParameters();
-            $customRules = $this->customParamsDocComment($reflectionMethod->getDocComment());
+            $docComment       = $reflectionMethod->getDocComment();
+            $customRules      = $this->customParamsDocComment($docComment);
+            $customResponses  = $this->customResponsesDocComment($docComment);
+            $controllersInfo[$index]['responses'] = $customResponses;
             $controllersInfo[$index]['rules'] = [];
 
             foreach ($params as $param) {
@@ -326,14 +329,38 @@ private function customParamsDocComment($docComment): array
             if (Str::contains($comment, '@LRDparam')) {
                 $comment = trim(Str::replace(['@LRDparam', '*'], '', $comment));
 
-                $comment = explode(' ', $comment);
+                $comment = $this->multiexplode([' ', '|'], $comment);
 
                 if (count($comment) > 0) {
                     $params[$comment[0]] = array_values(array_filter($comment, fn($item) => $item != $comment[0]));
                 }
             }
         }
+        return $params;
+    }
+    private function customResponsesDocComment($docComment): array
+    {
+        $params = [];
+
+        foreach (explode("\n", $docComment) as $comment) {
+            if (Str::contains($comment, '@LRDresponses')) {
+                $comment = trim(Str::replace(['@LRDresponses', '*'], '', $comment));
 
+                $comment = $this->multiexplode([' ', '|'], $comment);
+
+                $params = $comment;
+            }
+        }
+        if (count($params) == 0) {
+            $params = config('request-docs.default_responses') ?? [];
+        }
         return $params;
     }
+
+    private function multiexplode($delimiters, $string) {
+
+        $ready = str_replace($delimiters, $delimiters[0], $string);
+        $launch = explode($delimiters[0], $ready);
+        return  $launch;
+    }    
 }

ui/src/components/ApiAction.tsx

@@ -30,6 +30,7 @@ interface IAPIInfo {
     httpMethod: string;
     rules: IAPIRule;
     docBlock: string;
+    responses: string[];
 }
 
 interface Props {
@@ -67,6 +68,22 @@ export default function ApiAction(props: Props) {
     const [responseHeaders, setResponseHeaders] = useState("");
     const [activeTab, setActiveTab] = useState('info');
 
+    const responsesText: any = {
+        "200": "OK",
+        "201": "Created",
+        "202": "Accepted",
+        "204": "No Content",
+        "400": "Bad Request",
+        "401": "Unauthorized",
+        "403": "Forbidden",
+        "404": "Not Found",
+        "405": "Method Not Allowed",
+        "422": "Unprocessable Entity",
+        "429": "Too Many Requests",
+        "500": "Internal Server Error",
+        "503": "Service Unavailable",
+    }
+
     const setGetCurlCommand = (queries: string) => {
         let curl = `curl -X ${method} "${host}/${lrdDocsItem.uri}${queries}"`
 
@@ -93,6 +110,14 @@ export default function ApiAction(props: Props) {
         }
         setCurlCommand(curl)
     }
+    const explode = (str: string, maxLength: number) => {
+        let buff = "";
+        const numOfLines = Math.floor(str.length/maxLength);
+        for(let i = 0; i<numOfLines+1; i++) {
+            buff += str.substr(i*maxLength, maxLength); if(i !== numOfLines) { buff += "\\<br/>"; }
+        }
+        return buff;
+    }        
 
     const handleSendRequest = () => {
         // update localstorage
@@ -147,7 +172,6 @@ export default function ApiAction(props: Props) {
             setTimeTaken(timeTaken)
             setResponseStatus(response.status)
             setResponseHeaders(JSON.stringify(Object.fromEntries(response.headers), null, 2))
-            showResponse()
             setSendingRequest(false)
             return response.json();
         }).then((data) => {
@@ -174,10 +198,12 @@ export default function ApiAction(props: Props) {
                 delete data._lrd
             }
             setResponseData(JSON.stringify(data, null, 2))
+            showResponse()
         }).catch((error) => {
             setError("Response error: " + error)
             setResponseStatus(500)
             setSendingRequest(false)
+            showResponse()
         })
 
     }
@@ -352,10 +378,24 @@ export default function ApiAction(props: Props) {
                                             <th>Curl</th>
                                             <td>
                                                 <small>
-                                                    <pre className='p-2 bg-base-300'>{curlCommand}</pre>
+                                                    <pre className='m-1 p-2 bg-base-300'>
+                                                        <div className='' dangerouslySetInnerHTML={{__html: explode(curlCommand, 70)}} />
+                                                    </pre>
                                                 </small>
                                             </td>
                                         </tr>
+                                        <tr>
+                                            <th>Responses</th>
+                                            <td>
+                                                {lrdDocsItem.responses.map((response) => (
+                                                    <div key={shortid.generate()}>
+                                                            <div className={`response response-${response}`}>
+                                                                - {response} &nbsp; {responsesText[response]}
+                                                            </div>
+                                                    </div>
+                                                ))}
+                                            </td>
+                                        </tr>
                                     </tbody>
                                 </table>
                             </div>

ui/src/global.css

@@ -71,15 +71,30 @@ td {
 .method-HEAD {
     @apply text-info;
 }
-.badge-200 {
+.badge-200,.badge-201,.badge-202,.response-204 {
     @apply bg-success;
 }
-.badge-422 {
+.badge-422,.badge-429 {
     @apply bg-warning;
 }
-.badge-400 {
+.badge-400,.badge-401,.badge-402,.badge-403,.badge-404,.badge-405 {
     @apply bg-error;
 }
-.badge-500 {
+.badge-500,.badge-501,.badge-502,.badge-503 {
     @apply bg-error;
 }
+.response {
+    @apply w-10/12 rounded bg-base-300 pl-3 pt-1 pb-1 mb-2 font-bold;
+}
+.response-200,.response-201,.response-202,.response-204 {
+    @apply bg-success text-green-800;
+}
+.response-422,.response-429 {
+    @apply bg-yellow-500 text-yellow-800;
+}
+.response-400,.response-401,.response-402,.response-403,.response-404,.response-405 {
+    @apply bg-red-300 text-red-800;
+}
+.response-500,.response-501,.response-502,.response-503 {
+    @apply bg-red-400 text-red-800;
+}