Merge pull request #177 from rakutentech/feature/types

Use native types

Author: kitloong

.github/workflows/phplint.yml

@@ -0,0 +1,41 @@
+on: [push]
+
+name: "CI PHP"
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    name: PHP lint
+
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/[email protected]
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install PHP with extensions
+        uses: shivammathur/setup-php@v2
+        with:
+          coverage: pcov
+          extensions: intl, gd, zip, pdo, sqlite, pdo_sqlite, dom, curl, libxml, mbstring, fileinfo, exif, iconv
+          ini-values: memory_limit=-1,disable_functions="",pcov.exclude="~(vendor|tests|node_modules)~",pcov.directory="./"
+          php-version: 8.2
+          tools: composer:v2
+
+      - name: Composer Install
+        run: |
+            composer require --no-interaction --no-update
+            composer install
+
+      - name: PHPLint
+        run: |
+            ./vendor/bin/phpcs
+
+      - name: PHPStan
+        run: |
+            ./vendor/bin/phpstan analyse

.github/workflows/phptest.yml

@@ -4,19 +4,33 @@ name: "CI PHP"
 
 jobs:
   test:
-    name: Test
 
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        php-versions: [7.4, 8.0.6, 8.1, 8.2]
+        php: [7.4, 8.0, 8.1, 8.2]
+        laravel: [8.*]
+        include:
+          - php: 8.0
+            laravel: 9.*
+          - php: 8.1
+            laravel: 9.*
+          - php: 8.2
+            laravel: 9.*
+          - php: 8.1
+            laravel: 10.*
+          - php: 8.2
+            laravel: 10.*
+
+    name: PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }}
 
     steps:
       - name: Cancel Previous Runs
         uses: styfle/[email protected]
         with:
-          access_token: ${{ github.token }}    
+          access_token: ${{ github.token }}
+
       - name: Checkout
         uses: actions/checkout@v2
 
@@ -26,22 +40,20 @@ jobs:
           coverage: pcov
           extensions: intl, gd, zip, pdo, sqlite, pdo_sqlite, dom, curl, libxml, mbstring, fileinfo, exif, iconv
           ini-values: memory_limit=-1,disable_functions="",pcov.exclude="~(vendor|tests|node_modules)~",pcov.directory="./"
-          php-version: ${{ matrix.php-versions }}
+          php-version: ${{ matrix.php }}
           tools: composer:v2
 
       - name: Composer Install
-        run: composer install
+        run: |
+            composer require "laravel/framework:${{ matrix.laravel }}" --no-interaction --no-update
+            composer install
 
       - name: PHPUNIT Tests
         run: |
             ./vendor/bin/phpunit --coverage-clover=coverage.xml
 
-      - name: PHPLint
-        run: |
-            ./vendor/bin/phpcs --standard=phpcs.xml --extensions=php --ignore=tests/migrations config/ src/
-
       - name: Upload to codecov
         uses: codecov/codecov-action@v3
         with:
-          name: PHP ${{ matrix.php-versions }}
+          name: PHP ${{ matrix.php }}
           files: coverage.xml

README.md

@@ -10,6 +10,15 @@
   Supports Open API 3.0.0
 </p>
 
+<p align="center">
+  <img src="https://github.com/rakutentech/laravel-request-docs/actions/workflows/node.yml/badge.svg?branch=master" alt="CI Node">
+  <img src="https://github.com/rakutentech/laravel-request-docs/actions/workflows/phptest.yml/badge.svg?branch=master" alt="CI PHP">
+  <a href="https://codecov.io/gh/rakutentech/laravel-request-docs"><img src="https://codecov.io/gh/rakutentech/laravel-request-docs/branch/master/graph/badge.svg?token=U6ZRDPY6QZ" alt="codecov"></a>
+  <a href="https://packagist.org/packages/rakutentech/laravel-request-docs"><img src="https://poser.pugx.org/rakutentech/laravel-request-docs/v/stable.png" alt="Latest Stable Version"></a>
+  <a href="https://packagist.org/packages/rakutentech/laravel-request-docs"><img src="http://poser.pugx.org/rakutentech/laravel-request-docs/downloads" alt="Total Downloads"></a>
+  <a href="LICENSE.md"><img src="https://poser.pugx.org/rakutentech/laravel-request-docs/license.png" alt="License"></a>
+</p>
+
 **Fast:** Install on any Laravel Project
 
 **Hassle Free:** Auto Generate API Documentation for request rules and parameters
@@ -52,7 +61,7 @@ Read more: https://medium.com/web-developer/laravel-automatically-generate-api-d
 You can install the package via composer:
 
 ```bash
-composer require rakutentech/laravel-request-docs --dev
+composer require rakutentech/laravel-request-docs
 ```
 
 
@@ -63,6 +72,18 @@ php artisan vendor:publish --tag=request-docs-config
 php artisan route:cache
 ```
 
+(optional) Add following middleware to your API, so that the sql logs, model events are captured.
+
+`app/Http/Kernel.php`
+
+```sh
+        'api' => [
+            ...
+            \Rakutentech\LaravelRequestDocs\LaravelRequestDocsMiddleware::class,
+            ... and so on
+
+```
+
 # Usage
 
 ## Dashboard

composer.json

@@ -27,6 +27,7 @@
         "brianium/paratest": "^6.2",
         "friendsofphp/php-cs-fixer": "^3.5",
         "nunomaduro/collision": "^5.3|^6.0",
+        "nunomaduro/larastan": "^1.0|^2.4",
         "orchestra/testbench": "^6.15|^7.0|^8.0",
         "phpunit/phpunit": "^9.3",
         "spatie/laravel-ray": "^1.23",
@@ -44,10 +45,10 @@
         }
     },
     "scripts": {
-        "psalm": "vendor/bin/psalm",
-        "phpcs": "vendor/bin/phpcs",
-        "test": "./vendor/bin/testbench package:test --parallel --no-coverage",
-        "test-coverage": "vendor/bin/phpunit --coverage-html coverage"
+        "phpstan": "phpstan analyse",
+        "phpcs": "phpcs",
+        "test": "testbench package:test --parallel --no-coverage",
+        "test-coverage": "phpunit --coverage-html coverage"
     },
     "config": {
         "sort-packages": true

config/request-docs.php

@@ -1,6 +1,7 @@
 <?php
 
 return [
+    'enabled' => true,
     // change it to true will make lrd to throw exception if rules in request class need to be changed
     // keep it false
     'debug' => false,
@@ -37,7 +38,7 @@
     'rules_methods' => [
         'rules'
     ],
-    // Can be overridden as // @LRDResponses 200|400|401
+    // Can be overridden as // @LRDresponses 200|400|401
     'default_responses' => [ "200", "400", "401", "403", "404", "405", "422", "429", "500", "503"],
 
     // By default, LRD group your routes by the first /path.

phpcs.xml

@@ -4,12 +4,18 @@
     <file>src</file>
     <file>tests</file>
 
-    <exclude-pattern type="relative-root">tests/*</exclude-pattern>
     <rule ref="PSR2"/>
     <rule ref="Generic.Files.LineLength">
       <properties>
        <property name="lineLimit" value="210"/>
        <property name="absoluteLineLimit" value="0"/>
       </properties>
     </rule>
+
+    <!-- Align corresponding assignment statement tokens -->
+    <rule ref="Generic.Formatting.MultipleStatementAlignment">
+        <properties>
+            <property name="error" value="true"/>
+        </properties>
+    </rule>
 </ruleset>

phpstan.neon

@@ -0,0 +1,19 @@
+includes:
+    - ./vendor/nunomaduro/larastan/extension.neon
+
+parameters:
+
+    paths:
+        - src
+        - tests
+
+    # The level 8 is the highest level
+    level: 5
+
+#    ignoreErrors:
+#        - '#PHPDoc tag @var#'
+#
+#    excludePaths:
+#        - ./*/*/FileToBeExcluded.php
+
+    checkMissingIterableValueType: false

phpunit.xml

@@ -16,7 +16,7 @@
     <env name="SESSION_DRIVER" value="array"/>
     <env name="QUEUE_DRIVER" value="sync"/>
     <env name="MAIL_DRIVER" value="log"/>
-    <env name="DB_CONNECTION" value="sqlite_testing"/>
+    <env name="DB_CONNECTION" value="sqlite"/>
     <env name="DB_DATABASE" value=":memory:"/>
   </php>
 </phpunit>

src/Controllers/LaravelRequestDocsController.php

@@ -2,54 +2,70 @@
 
 namespace Rakutentech\LaravelRequestDocs\Controllers;
 
+use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
+use Illuminate\Routing\Controller;
 use Rakutentech\LaravelRequestDocs\LaravelRequestDocs;
 use Rakutentech\LaravelRequestDocs\LaravelRequestDocsToOpenApi;
-use Illuminate\Routing\Controller;
+use Symfony\Component\HttpFoundation\BinaryFileResponse;
 
 class LaravelRequestDocsController extends Controller
 {
-    private $laravelRequestDocs;
+    private LaravelRequestDocs          $laravelRequestDocs;
+    private LaravelRequestDocsToOpenApi $laravelRequestDocsToOpenApi;
 
     public function __construct(LaravelRequestDocs $laravelRequestDoc, LaravelRequestDocsToOpenApi $laravelRequestDocsToOpenApi)
     {
-        $this->laravelRequestDocs = $laravelRequestDoc;
+        $this->laravelRequestDocs          = $laravelRequestDoc;
         $this->laravelRequestDocsToOpenApi = $laravelRequestDocsToOpenApi;
     }
 
-    public function index(Request $request)
+    /**
+     * @codeCoverageIgnore
+     */
+    public function index(Request $request): Response
     {
-        return view('request-docs::index');
+        return response()->view('request-docs::index');
     }
-    public function api(Request $request)
-    {
-        $docs = $this->laravelRequestDocs->getDocs();
-        $docs = $this->laravelRequestDocs->sortDocs($docs, $request->sort);
-        $docs = $this->laravelRequestDocs->groupDocs($docs, $request->groupby);
 
-        $showGet = $request->has('showGet') ? $request->showGet == 'true' : true;
-        $showPost = $request->has('showPost') ? $request->showPost == 'true' : true;
-        $showPut = $request->has('showPut') ? $request->showPut == 'true' : true;
-        $showPatch = $request->has('showPatch') ? $request->showPatch == 'true' : true;
-        $showDelete = $request->has('showDelete') ? $request->showDelete == 'true' : true;
-        $showHead = $request->has('showHead') ? $request->showHead == 'true' : true;
+    /**
+     * @throws \ReflectionException
+     * @throws \Throwable
+     */
+    public function api(Request $request): JsonResponse
+    {
+        $showGet    = !$request->has('showGet') || $request->input('showGet') === 'true';
+        $showPost   = !$request->has('showPost') || $request->input('showPost') == 'true';
+        $showPut    = !$request->has('showPut') || $request->input('showPut') === 'true';
+        $showPatch  = !$request->has('showPatch') || $request->input('showPatch') === 'true';
+        $showDelete = !$request->has('showDelete') || $request->input('showDelete') === 'true';
+        $showHead   = !$request->has('showHead') || $request->input('showHead') === 'true';
 
-        $docs = $this->laravelRequestDocs->filterByMethods(
-            $docs,
+        // Get a list of Doc with route and rules information.
+        // If user defined `Route::match(['get', 'post'], 'uri', ...)`,
+        // only a single Doc will be generated.
+        $docs = $this->laravelRequestDocs->getDocs(
             $showGet,
             $showPost,
             $showPut,
             $showPatch,
             $showDelete,
-            $showHead
+            $showHead,
         );
-        if ($request->openapi) {
+
+        // Loop and split Doc by the `methods` property.
+        // `Route::match([...n], 'uri', ...)` will generate n number of Doc.
+        $docs = $this->laravelRequestDocs->splitByMethods($docs);
+        $docs = $this->laravelRequestDocs->sortDocs($docs, $request->input('sort'));
+        $docs = $this->laravelRequestDocs->groupDocs($docs, $request->input('groupby'));
+
+        if ($request->input('openapi')) {
             return response()->json(
-                $this->laravelRequestDocsToOpenApi->openApi($docs)->toArray(),
+                $this->laravelRequestDocsToOpenApi->openApi($docs->all())->toArray(),
                 Response::HTTP_OK,
                 [
-                    'Content-type'=> 'application/json; charset=utf-8'
+                    'Content-type' => 'application/json; charset=utf-8'
                 ],
                 JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
             );
@@ -59,12 +75,17 @@ public function api(Request $request)
             $docs,
             Response::HTTP_OK,
             [
-                'Content-type'=> 'application/json; charset=utf-8',
+                'Content-type' => 'application/json; charset=utf-8',
             ],
             JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
         );
     }
 
+    /**
+     * @codeCoverageIgnore
+     * @param  \Illuminate\Http\Request  $request
+     * @return \Symfony\Component\HttpFoundation\BinaryFileResponse|\Illuminate\Http\JsonResponse
+     */
     public function assets(Request $request)
     {
         $path = explode('/', $request->path());
@@ -95,7 +116,7 @@ public function assets(Request $request)
 
             // set cache control headers
             $headers['Cache-Control'] = 'public, max-age=1800';
-            $headers['Expires'] = gmdate('D, d M Y H:i:s \G\M\T', time() + 1800);
+            $headers['Expires']       = gmdate('D, d M Y H:i:s \G\M\T', time() + 1800);
             return response()->file($path, $headers);
         }
         return response()->json(['error' => 'file not found'], 404);