Merge pull request #523 from mpociot/update-config

Switch to `base_url` config var for base URL in docs and collection

Author: shalvah

TODO.md

@@ -3,3 +3,4 @@
 - Add tests on output (deterministic)
 - Bring `bindings` outside of `response_calls`
 - Should `routes.*.apply.response_calls.headers` be replaced by `routes.*.apply.headers`?
+- Implement debug flag

config/apidoc.php

@@ -13,6 +13,12 @@
      */
     'router' => 'laravel',
 
+    /*
+     * The base URL to be used in examples and the Postman collection.
+     * By default, this will be the value of config('app.url').
+     */
+    'base_url' => config('app.url'),
+
     /*
      * Generate a Postman collection in addition to HTML docs.
      */

docs/config.md

@@ -8,6 +8,9 @@ This is the file path where the generated documentation will be written to. Note
 ## `router`
 The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**)
 
+## `base_url`
+The base URL to be used in examples and the Postman collection. By default, this will be the value of config('app.url').
+
 ## `postman`
 This package can automatically generate a Postman collection for your routes, along with the documentation. This section is where you can configure (or disable) that.
 

resources/views/partials/example-requests/bash.blade.php

@@ -1,5 +1,5 @@
 ```bash
-curl -X {{$route['methods'][0]}} {{$route['methods'][0] == 'GET' ? '-G ' : ''}}"{{ trim(config('app.docs_url') ?: config('app.url'), '/')}}/{{ ltrim($route['boundUri'], '/') }}" @if(count($route['headers']))\
+curl -X {{$route['methods'][0]}} {{$route['methods'][0] == 'GET' ? '-G ' : ''}}"{{ rtrim($baseUrl, '/')}}/{{ ltrim($route['boundUri'], '/') }}" @if(count($route['headers']))\
 @foreach($route['headers'] as $header => $value)
     -H "{{$header}}: {{$value}}"@if(! ($loop->last) || ($loop->last && count($route['bodyParameters']))) \
 @endif

resources/views/partials/example-requests/javascript.blade.php

@@ -1,5 +1,5 @@
 ```javascript
-const url = new URL("{{ rtrim(config('app.docs_url') ?: config('app.url'), '/') }}/{{ ltrim($route['boundUri'], '/') }}");
+const url = new URL("{{ rtrim($baseUrl, '/') }}/{{ ltrim($route['boundUri'], '/') }}");
 @if(count($route['queryParameters']))
 
     let params = {

resources/views/partials/example-requests/php.blade.php

@@ -1,7 +1,7 @@
 ```php
 
 $client = new \GuzzleHttp\Client();
-$response = $client->{{ strtolower($route['methods'][0]) }}("{{ $route['boundUri'] }}", [
+$response = $client->{{ strtolower($route['methods'][0]) }}("{{ rtrim($baseUrl, '/') . '/' . $route['boundUri'] }}", [
 @if(!empty($route['headers']))
     'headers' => [
     @foreach($route['headers'] as $header => $value)

src/Commands/GenerateDocumentation.php

@@ -14,6 +14,7 @@
 use Mpociot\ApiDoc\Tools\RouteMatcher;
 use Mpociot\Documentarian\Documentarian;
 use Mpociot\ApiDoc\Postman\CollectionWriter;
+use Mpociot\ApiDoc\Tools\DocumentationConfig;
 
 class GenerateDocumentation extends Command
 {
@@ -35,6 +36,11 @@ class GenerateDocumentation extends Command
 
     private $routeMatcher;
 
+    /**
+     * @var DocumentationConfig
+     */
+    private $docConfig;
+
     public function __construct(RouteMatcher $routeMatcher)
     {
         parent::__construct();
@@ -48,20 +54,23 @@ public function __construct(RouteMatcher $routeMatcher)
      */
     public function handle()
     {
+        $this->docConfig = new DocumentationConfig(config('apidoc'));
+
         try {
-            URL::forceRootUrl(config('app.url'));
+            URL::forceRootUrl($this->docConfig->get('base_url'));
         } catch (\Exception $e) {
-            echo "Warning: Couldn't force base url as Lumen currently doesn't have the forceRootUrl method.\n";
+            echo "Warning: Couldn't force base url as your version of Lumen doesn't have the forceRootUrl method.\n";
             echo "You should probably double check URLs in your generated documentation.\n";
         }
-        $usingDingoRouter = strtolower(config('apidoc.router')) == 'dingo';
+        $usingDingoRouter = strtolower($this->docConfig->get('router')) == 'dingo';
+        $routes = $this->docConfig->get('routes');
         if ($usingDingoRouter) {
-            $routes = $this->routeMatcher->getDingoRoutesToBeDocumented(config('apidoc.routes'));
+            $routes = $this->routeMatcher->getDingoRoutesToBeDocumented($routes);
         } else {
-            $routes = $this->routeMatcher->getLaravelRoutesToBeDocumented(config('apidoc.routes'));
+            $routes = $this->routeMatcher->getLaravelRoutesToBeDocumented($routes);
         }
 
-        $generator = new Generator(config('apidoc.faker_seed'));
+        $generator = new Generator($this->docConfig);
         $parsedRoutes = $this->processRoutes($generator, $routes);
         $parsedRoutes = collect($parsedRoutes)->groupBy('group')
             ->sortBy(static function ($group) {
@@ -79,7 +88,7 @@ public function handle()
      */
     private function writeMarkdown($parsedRoutes)
     {
-        $outputPath = config('apidoc.output');
+        $outputPath = $this->docConfig->get('output');
         $targetFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'index.md';
         $compareFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'.compare.md';
         $prependFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'prepend.md';
@@ -89,7 +98,7 @@ private function writeMarkdown($parsedRoutes)
             ->with('outputPath', ltrim($outputPath, 'public/'))
             ->with('showPostmanCollectionButton', $this->shouldGeneratePostmanCollection());
 
-        $settings = ['languages' => config('apidoc.example_languages')];
+        $settings = ['languages' => $this->docConfig->get('example_languages')];
         $parsedRouteOutput = $parsedRoutes->map(function ($routeGroup) use ($settings) {
             return $routeGroup->map(function ($route) use ($settings) {
                 if (count($route['cleanBodyParameters']) && ! isset($route['headers']['Content-Type'])) {
@@ -98,6 +107,7 @@ private function writeMarkdown($parsedRoutes)
                 $route['output'] = (string) view('apidoc::partials.route')
                     ->with('route', $route)
                     ->with('settings', $settings)
+                    ->with('baseUrl', $this->docConfig->get('base_url'))
                     ->render();
 
                 return $route;
@@ -150,7 +160,7 @@ private function writeMarkdown($parsedRoutes)
             ->with('infoText', $infoText)
             ->with('prependMd', $prependFileContents)
             ->with('appendMd', $appendFileContents)
-            ->with('outputPath', config('apidoc.output'))
+            ->with('outputPath', $this->docConfig->get('output'))
             ->with('showPostmanCollectionButton', $this->shouldGeneratePostmanCollection())
             ->with('parsedRoutes', $parsedRouteOutput);
 
@@ -168,7 +178,7 @@ private function writeMarkdown($parsedRoutes)
             ->with('infoText', $infoText)
             ->with('prependMd', $prependFileContents)
             ->with('appendMd', $appendFileContents)
-            ->with('outputPath', config('apidoc.output'))
+            ->with('outputPath', $this->docConfig->get('output'))
             ->with('showPostmanCollectionButton', $this->shouldGeneratePostmanCollection())
             ->with('parsedRoutes', $parsedRouteOutput);
 
@@ -188,7 +198,7 @@ private function writeMarkdown($parsedRoutes)
             file_put_contents($outputPath.DIRECTORY_SEPARATOR.'collection.json', $this->generatePostmanCollection($parsedRoutes));
         }
 
-        if ($logo = config('apidoc.logo')) {
+        if ($logo = $this->docConfig->get('logo')) {
             copy(
                 $logo,
                 $outputPath.DIRECTORY_SEPARATOR.'images'.DIRECTORY_SEPARATOR.'logo.png'
@@ -274,7 +284,7 @@ private function isRouteVisibleForDocumentation($action)
      */
     private function generatePostmanCollection(Collection $routes)
     {
-        $writer = new CollectionWriter($routes);
+        $writer = new CollectionWriter($routes, $this->docConfig->get('base_url'));
 
         return $writer->getCollection();
     }
@@ -286,6 +296,6 @@ private function generatePostmanCollection(Collection $routes)
      */
     private function shouldGeneratePostmanCollection()
     {
-        return config('apidoc.postman.enabled', is_bool(config('apidoc.postman')) ? config('apidoc.postman') : false);
+        return $this->docConfig->get('postman.enabled', is_bool($this->docConfig->get('postman')) ? $this->docConfig->get('postman') : false);
     }
 }

src/Postman/CollectionWriter.php

@@ -13,19 +13,30 @@ class CollectionWriter
      */
     private $routeGroups;
 
+    /**
+     * @var string
+     */
+    private $baseUrl;
+
     /**
      * CollectionWriter constructor.
      *
      * @param Collection $routeGroups
      */
-    public function __construct(Collection $routeGroups)
+    public function __construct(Collection $routeGroups, $baseUrl)
     {
         $this->routeGroups = $routeGroups;
+        $this->baseUrl = $baseUrl;
     }
 
     public function getCollection()
     {
-        URL::forceRootUrl(config('app.url'));
+        try {
+            URL::forceRootUrl($this->baseUrl);
+        } catch (\Exception $e) {
+            echo "Warning: Couldn't force base url as your version of Lumen doesn't have the forceRootUrl method.\n";
+            echo "You should probably double check URLs in your generated Postman collection.\n";
+        }
 
         $collection = [
             'variables' => [],

src/Tools/DocumentationConfig.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Mpociot\ApiDoc\Tools;
+
+class DocumentationConfig
+{
+    private $data;
+
+    public function __construct(array $config = [])
+    {
+        $this->data = $config;
+    }
+
+    public function get($key, $default = null)
+    {
+        return data_get($this->data, $key, $default);
+    }
+}

src/Tools/Generator.php

@@ -15,14 +15,14 @@ class Generator
     use ParamHelpers;
 
     /**
-     * @var string The seed to be used with Faker.
-     * Useful when you want to always have the same fake output.
+     * @var DocumentationConfig
      */
-    private $fakerSeed = null;
+    private $config;
 
-    public function __construct(string $fakerSeed = null)
+    public function __construct(DocumentationConfig $config = null)
     {
-        $this->fakerSeed = $fakerSeed;
+        // If no config is injected, pull from global
+        $this->config = $config ?: new DocumentationConfig(config('apidoc'));
     }
 
     /**
@@ -296,7 +296,7 @@ protected function getRouteGroup(ReflectionClass $controller, ReflectionMethod $
             }
         }
 
-        return config('apidoc.default_group', 'general');
+        return $this->config->get(('default_group'));
     }
 
     private function normalizeParameterType($type)
@@ -313,8 +313,8 @@ private function normalizeParameterType($type)
     private function generateDummyValue(string $type)
     {
         $faker = Factory::create();
-        if ($this->fakerSeed) {
-            $faker->seed($this->fakerSeed);
+        if ($this->config->get('faker_seed')) {
+            $faker->seed($this->config->get('faker_seed'));
         }
         $fakeFactories = [
             'integer' => function () use ($faker) {