Merge pull request #659 from andrey-helldar/patch-2019-12-17-11-42

Implemented autoload of routes

config/apidoc.php

@@ -9,6 +9,29 @@ return [
      */
     'type' => 'static',
 
+    /*
+     * Settings for `laravel` type output.
+     */
+    'laravel' => [
+        /*
+         * Whether to automatically create a docs endpoint for you to view your generated docs.
+         * If this is false, you can still set up routing manually.
+         */
+        'autoload' => false,
+
+        /*
+         * URL path to use for the docs endpoint (if `autoload` is true).
+         *
+         * By default, `/doc` opens the HTML page, and `/doc.json` downloads the Postman collection.
+         */
+        'docs_url' => '/doc',
+
+        /*
+         * Middleware to attach to the docs endpoint (if `autoload` is true).
+         */
+        'middleware' => [],
+    ],
+
     /*
      * The router to be used (Laravel or Dingo).
      */

docs/config.md

@@ -9,14 +9,21 @@ This is the type of documentation output to generate.
 
 > In both instances, the source markdown file will be generated in `resources/docs/source`.
 
-If you're using `laravel` type, you can call `\Mpociot\ApiDoc\ApiDoc::routes()` from your routes file (usually `routes/web.php`). This method will create a `/doc` route for your documentation, along with a `/doc.json` variant that will return the Postman collection, if you have that enabled. This method returns the route, so you can call additional methods to customise it (by adding middleware, for instance). You can also pass in the path you'd like to use instead.
+## `laravel`
+If you're using `laravel` type output, this package can automatically set up an endpoint for you to view your generated docs. You can configure this here.
+
+### `autoload`
+Set this to `true` if you want the documentation endpoint to be automatically set up for you. Default: `false` (*note that this will change in the next major release*)
+
+You may, of course, use your own routing instead of using `autoload`.
+
+### `docs_url`
+The path for the HTMl documentation endpoint (if `autoload` is true). Your Postman collection (if you have that enabled) will be at this path + '.json' (eg `/doc.json`). Default: `/doc`
 
-```php
-\Mpociot\ApiDoc\ApiDoc::routes("/apidoc")->middleware("auth.basic");
-```
 > Note: There is currently a known issue with using `/docs` as the path for `laravel` docs. You should not use it, as it conflicts with the folder structure in the `public` folder and may confuse the webserver.
 
-You may, of course, set up your own routing instead of using the `routes()` helper.
+### `middleware`
+Here, you can specify middleware to be attached to the documentation endpoint (if `autoload` is true).
 
 ## `router`
 The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**)

routes/laravel.php

@@ -0,0 +1,14 @@
+<?php
+
+use Illuminate\Support\Facades\Route;
+
+$prefix = config('apidoc.laravel.docs_url', '/doc');
+$middleware = config('apidoc.laravel.middleware', []);
+
+Route::prefix($prefix)
+    ->namespace('\Mpociot\ApiDoc\Http')
+    ->middleware($middleware)
+    ->group(function () {
+        Route::get('/', 'Controller@html')->name('apidoc');
+        Route::get('.json', 'Controller@json')->name('apidoc.json');
+    });

src/ApiDoc.php

@@ -3,23 +3,34 @@
 namespace Mpociot\ApiDoc;
 
 use Illuminate\Support\Facades\Route;
-use Illuminate\Support\Facades\Storage;
 
 class ApiDoc
 {
+    /**
+     * Binds the ApiDoc routes into the controller.
+     *
+     * @deprecated Use autoload routes instead (`config/apidoc.php`: `routes > laravel > autoload`).
+     *
+     * @param string $path
+     */
     public static function routes($path = '/doc')
     {
-        return Route::get("$path{format?}", function (?string $format = null) {
-            if ($format == '.json') {
-                return response(
-                    Storage::disk('local')->get('apidoc/collection.json'),
-                    200,
-                    ['Content-type' => 'application/json']
-
-                );
-            }
+        Route::prefix($path)
+            ->namespace('\Mpociot\ApiDoc\Http')
+            ->middleware(static::middleware())
+            ->group(function () {
+                Route::get('/', 'Controller@html')->name('apidoc');
+                Route::get('.json', 'Controller@json')->name('apidoc.json');
+            });
+    }
 
-            return view('apidoc.index');
-        })->name('apidoc');
+    /**
+     * Get the middlewares for Laravel routes.
+     *
+     * @return array
+     */
+    protected static function middleware()
+    {
+        return config('apidoc.laravel.middleware', []);
     }
 }

src/ApiDocGeneratorServiceProvider.php

@@ -28,6 +28,8 @@ class ApiDocGeneratorServiceProvider extends ServiceProvider
 
         $this->mergeConfigFrom(__DIR__.'/../config/apidoc.php', 'apidoc');
 
+        $this->bootRoutes();
+
         if ($this->app->runningInConsole()) {
             $this->commands([
                 GenerateDocumentation::class,
@@ -47,4 +49,19 @@ class ApiDocGeneratorServiceProvider extends ServiceProvider
     public function register()
     {
     }
+
+    /**
+     * Initializing routes in the application.
+     */
+    protected function bootRoutes()
+    {
+        if (
+            config('apidoc.type', 'static') === 'laravel' &&
+            config('apidoc.laravel.autoload', false)
+        ) {
+            $this->loadRoutesFrom(
+                __DIR__.'/../routes/laravel.php'
+            );
+        }
+    }
 }

src/Http/Controller.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Mpociot\ApiDoc\Http;
+
+use Illuminate\Support\Facades\Storage;
+
+class Controller
+{
+    public function html()
+    {
+        return view('apidoc.index');
+    }
+
+    /**
+     * @throws \Illuminate\Contracts\Filesystem\FileNotFoundException
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function json()
+    {
+        return response()->json(
+            Storage::disk('local')->get('apidoc/collection.json')
+        );
+    }
+}