Merge pull request #443 from ewerkema/name

Specify more Postman parameters

README.md

@@ -45,7 +45,7 @@ Before you can generate your documentation, you'll need to configure a few thing
 This is the file path where the generated documentation will be written to. Default: **public/docs**
 
 - `postman`
-Set this option to true if you want a Postman collection to be generated along with the documentation. Default: **true**
+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.
 
 - `router`
 The router to use when processing the route (can be Laravel or Dingo. Defaults to **Laravel**)

config/apidoc.php

@@ -15,7 +15,22 @@ return [
     /*
      * Generate a Postman collection in addition to HTML docs.
      */
-    'postman' => true,
+    'postman' => [
+        /*
+         * Specify whether the Postman collection should be generated.
+         */
+        'enabled' => true,
+
+        /*
+         * The name for the exported Postman collection. Default: config('app.name')." API"
+         */
+        'name' => null,
+
+        /*
+         * The description for the exported Postman collection.
+         */
+        'description' => null,
+    ],
 
     /*
      * The routes for which documentation should be generated.

src/Commands/GenerateDocumentation.php

@@ -79,7 +79,7 @@ class GenerateDocumentation extends Command
 
         $infoText = view('apidoc::partials.info')
             ->with('outputPath', ltrim($outputPath, 'public/'))
-            ->with('showPostmanCollectionButton', config('apidoc.postman'));
+            ->with('showPostmanCollectionButton', $this->shouldGeneratePostmanCollection());
 
         $parsedRouteOutput = $parsedRoutes->map(function ($routeGroup) {
             return $routeGroup->map(function ($route) {
@@ -138,7 +138,7 @@ class GenerateDocumentation extends Command
             ->with('prependMd', $prependFileContents)
             ->with('appendMd', $appendFileContents)
             ->with('outputPath', config('apidoc.output'))
-            ->with('showPostmanCollectionButton', config('apidoc.postman'))
+            ->with('showPostmanCollectionButton', $this->shouldGeneratePostmanCollection())
             ->with('parsedRoutes', $parsedRouteOutput);
 
         if (! is_dir($outputPath)) {
@@ -156,7 +156,7 @@ class GenerateDocumentation extends Command
             ->with('prependMd', $prependFileContents)
             ->with('appendMd', $appendFileContents)
             ->with('outputPath', config('apidoc.output'))
-            ->with('showPostmanCollectionButton', config('apidoc.postman'))
+            ->with('showPostmanCollectionButton', $this->shouldGeneratePostmanCollection())
             ->with('parsedRoutes', $parsedRouteOutput);
 
         file_put_contents($compareFile, $compareMarkdown);
@@ -169,7 +169,7 @@ class GenerateDocumentation extends Command
 
         $this->info('Wrote HTML documentation to: '.$outputPath.'/index.html');
 
-        if (config('apidoc.postman')) {
+        if ($this->shouldGeneratePostmanCollection()) {
             $this->info('Generating Postman collection');
 
             file_put_contents($outputPath.DIRECTORY_SEPARATOR.'collection.json', $this->generatePostmanCollection($parsedRoutes));
@@ -260,4 +260,14 @@ class GenerateDocumentation extends Command
 
         return $writer->getCollection();
     }
+
+    /**
+     * Checks config if it should generate Postman collection.
+     *
+     * @return bool
+     */
+    private function shouldGeneratePostmanCollection()
+    {
+        return config('apidoc.postman.enabled', is_bool(config('apidoc.postman')) ? config('apidoc.postman') : false);
+    }
 }

src/Postman/CollectionWriter.php

@@ -4,6 +4,7 @@ namespace Mpociot\ApiDoc\Postman;
 
 use Ramsey\Uuid\Uuid;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\URL;
 
 class CollectionWriter
 {
@@ -24,12 +25,14 @@ class CollectionWriter
 
     public function getCollection()
     {
+        URL::forceRootUrl(config('app.url'));
+
         $collection = [
             'variables' => [],
             'info' => [
-                'name' => '',
+                'name' => config('apidoc.postman.name') ?: config('app.name').' API',
                 '_postman_id' => Uuid::uuid4()->toString(),
-                'description' => '',
+                'description' => config('apidoc.postman.description') ?: '',
                 'schema' => 'https://schema.getpostman.com/json/collection/v2.0.0/collection.json',
             ],
             'item' => $this->routeGroups->map(function ($routes, $groupName) {

tests/Fixtures/collection.json

@@ -1 +1 @@
-{"variables":[],"info":{"name":"","_postman_id":"","description":"","schema":"https:\/\/schema.getpostman.com\/json\/collection\/v2.0.0\/collection.json"},"item":[{"name":"Group A","description":"","item":[{"name":"Example title.","request":{"url":"http:\/\/localhost\/api\/test","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"This will be the long description.\nIt can also be multiple lines long.","response":[]}},{"name":"http:\/\/localhost\/api\/responseTag","request":{"url":"http:\/\/localhost\/api\/responseTag","method":"POST","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}}]}]}
+{"variables":[],"info":{"name":"Laravel API","_postman_id":"","description":"","schema":"https:\/\/schema.getpostman.com\/json\/collection\/v2.0.0\/collection.json"},"item":[{"name":"Group A","description":"","item":[{"name":"Example title.","request":{"url":"http:\/\/localhost\/api\/test","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"This will be the long description.\nIt can also be multiple lines long.","response":[]}},{"name":"http:\/\/localhost\/api\/responseTag","request":{"url":"http:\/\/localhost\/api\/responseTag","method":"POST","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}}]}]}

tests/Fixtures/collection_updated_url.json

@@ -0,0 +1 @@
+{"variables":[],"info":{"name":"Laravel API","_postman_id":"","description":"","schema":"https:\/\/schema.getpostman.com\/json\/collection\/v2.0.0\/collection.json"},"item":[{"name":"Group A","description":"","item":[{"name":"Example title.","request":{"url":"http:\/\/yourapp.app\/api\/test","method":"GET","body":{"mode":"formdata","formdata":[]},"description":"This will be the long description.\nIt can also be multiple lines long.","response":[]}},{"name":"http:\/\/yourapp.app\/api\/responseTag","request":{"url":"http:\/\/yourapp.app\/api\/responseTag","method":"POST","body":{"mode":"formdata","formdata":[]},"description":"","response":[]}}]}]}

tests/GenerateDocumentationTest.php

@@ -7,6 +7,7 @@ use RecursiveIteratorIterator;
 use RecursiveDirectoryIterator;
 use Orchestra\Testbench\TestCase;
 use Illuminate\Support\Facades\App;
+use Illuminate\Support\Facades\Config;
 use Illuminate\Contracts\Console\Kernel;
 use Mpociot\ApiDoc\Tests\Fixtures\TestController;
 use Mpociot\ApiDoc\ApiDocGeneratorServiceProvider;
@@ -229,6 +230,22 @@ class GenerateDocumentationTest extends TestCase
         $this->assertEquals($generatedCollection, $fixtureCollection);
     }
 
+    /** @test */
+    public function generated_postman_collection_can_have_custom_url()
+    {
+        Config::set('app.url', 'http://yourapp.app');
+        RouteFacade::get('/api/test', TestController::class.'@withEndpointDescription');
+        RouteFacade::post('/api/responseTag', TestController::class.'@withResponseTag');
+
+        config(['apidoc.routes.0.match.prefixes' => ['api/*']]);
+        $this->artisan('apidoc:generate');
+
+        $generatedCollection = json_decode(file_get_contents(__DIR__.'/../public/docs/collection.json'));
+        $generatedCollection->info->_postman_id = '';
+        $fixtureCollection = json_decode(file_get_contents(__DIR__.'/Fixtures/collection_updated_url.json'));
+        $this->assertEquals($generatedCollection, $fixtureCollection);
+    }
+
     /** @test */
     public function can_append_custom_http_headers()
     {