Merge pull request #126 from rakutentech/feature/v2-bugs

Feature/v2 bugs and features

Author: kevincobain2000

.github/workflows/releaser.yml

@@ -0,0 +1,44 @@
+on:
+  push:
+    branches:
+      - master
+
+name: "CI Node"
+
+jobs:
+  test:
+    name: Test
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-versions: [18]
+
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.9.1
+        with:
+          access_token: ${{ github.token }}    
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-versions }}
+
+      - name: NPM Install
+        working-directory: ./ui
+        run: npm install
+
+      - name: Lint, build/export
+        working-directory: ./ui
+        run: |
+          npm run lint
+          npm run export
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v4
+
+
+

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

@@ -31,11 +31,11 @@
 
     // https://github.com/rakutentech/laravel-request-docs/pull/92
     // When rules are put in other method than rules()
-    'request_methods' => [
-        'rules',
-        'onCreate',
-        'onUpdate',
+    '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) {
@@ -214,7 +217,7 @@ public function appendRequestRules(array $controllersInfo): array
                     //throw $th;
                 }
 
-                foreach (config('request-docs.request_methods') as $requestMethod) {
+                foreach (config('request-docs.rules_methods') as $requestMethod) {
                     if ($requestClass && method_exists($requestClass, $requestMethod)) {
                         try {
                             $controllersInfo[$index]['rules'] = array_merge($controllersInfo[$index]['rules'], $this->flattenRules($requestClass->$requestMethod()));
@@ -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;
+    }
 }

tests/LRDTest.php

@@ -10,7 +10,7 @@ public function testGetDocs()
     {
         $docs = $this->lrd->getDocs();
 
-        $docSize = 9;
+        $docSize = 10;
         $firstDoc = $docs[0];
         $this->assertCount($docSize, $firstDoc);
         $this->assertArrayHasKey('uri', $firstDoc);

ui/README.md

@@ -8,6 +8,11 @@ npm install
 npm run dev
 ```
 
+**Open in Browser** http://localhost:3000?api=http://localhost:3000/sample.json
+
+
+### Developing with Laravel
+
 #### Step 1
 
 **Optional** Enable CORS on Laravel to allow localhost:3000

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;
+}