Merge remote-tracking branch 'origin/master'

shalvah · shalvah · commit 812282084092 · 2020-08-23T21:11:04.000+01:00
diff --git a/config/scribe.php b/config/scribe.php
@@ -116,12 +116,9 @@
      * Generate a Postman collection in addition to HTML docs.
      * For 'static' docs, the collection will be generated to public/docs/collection.json.
      * For 'laravel' docs, it will be generated to storage/app/scribe/collection.json.
-     * Setting `laravel.autoload` to true (above) will add routes for both the HTML and the Postman collection.
+     * Setting `laravel.add_routes` to true (above) will also add a route for the collection.
      */
     'postman' => [
-        /*
-         * Specify whether the Postman collection should be generated.
-         */
         'enabled' => true,
 
         /*
@@ -140,10 +137,30 @@
          * https://schema.getpostman.com/json/collection/v2.0.0/docs/index.html
          */
         'auth' => null,
+
+        /*
+         * Manually override some generated content in the spec. Dot notation is supported.
+         */
+        'overrides' => [
+            // 'info.version' => '2.0.0',
+        ],
     ],
 
+    /*
+     * Generate an OpenAPI spec file in addition to docs webpage.
+     * For 'static' docs, the collection will be generated to public/docs/openapi.yaml.
+     * For 'laravel' docs, it will be generated to storage/app/scribe/openapi.yaml.
+     * Setting `laravel.add_routes` to true (above) will also add a route for the spec.
+     */
     'openapi' => [
         'enabled' => true,
+
+        /*
+         * Manually override some generated content in the spec. Dot notation is supported.
+         */
+        'overrides' => [
+            // 'info.version' => '2.0.0',
+        ],
     ],
 
     /*
diff --git a/docs/config.md b/docs/config.md
@@ -61,19 +61,23 @@ For `static` output, the collection will be created in `public/docs/collection.j
 
 - `enabled`: Whether or not to generate a Postman API collection. Default: `true`
 
+- `overrides`: List of fields to apply to the generated collection. Dot notation is supported. For instance, if you'd like to override the version (in the `info` object, you can set `overrides` to `['info.version' => '2.0.0']`.
+
 - `description`: The description for the generated Postman collection.
 
 - `base_url`: The base URL to be used in the Postman collection. If this is null, Scribe will use the value of [`base_url`](#base_url) set above.
 
 - `auth`: The "Auth" section that should appear in the postman collection. See the [Postman schema docs](https://schema.getpostman.com/json/collection/v2.0.0/docs/index.html) for more information.
 
 ### `openapi`
-Scribe can also generate an OpenAPI (Swagger) spec for your routes. This section is where you can configure or disable that.
+Scribe can also generate an OpenAPI (Swagger) spec for your routes (disabled by default). This section is where you can configure or enable that.
 
 For `static` output, the spec will be created in `public/docs/openapi.yaml`. For `laravel` output, the spec will be generated to `storage/app/scribe/openapi.yaml`. Setting `laravel.add_routes` to `true` will add a `/docs.openapi` endpoint to fetch it.
 
 - `enabled`: Whether or not to generate an OpenAPI spec. Default: `false`
 
+- `overrides`: List of fields to apply to the generated spec. Dot notation is supported. For instance, if you'd like to override the version (in the `info` object, you can set `overrides` to `['info.version' => '2.0.0']`.
+
 ## Extraction settings
 ### `router`
 The router to use when processing your routes. Can be `laravel` or `dingo`. Defaults to `laravel`.
diff --git a/docs/generating-documentation.md b/docs/generating-documentation.md
@@ -23,6 +23,8 @@ You can configure Postman collection generation in the `postman` section of your
 
 - To turn it off, set the `postman.enabled` config option to false.
 
+- To override some fields in the generated collection, set the `openapi.overrides` config option to your changes. You can use dot notation to update specific nested fields. For instance, `['info.version' => '2.0.0']` will override the 'version` key in the 'info` object whenever generating.
+
 - The base URL used in the Postman collection is the value of `config('app.url')` by default. To change this, set the value of the `postman.base_url` key.
 
 - The name of the Postman collection will be derived from `config('app.name')` by default. To change this, set the value of the `title` key (not in the `postman` array). This will also set the title for your docs HTML page.
@@ -34,6 +36,8 @@ Scribe can also generate an OpenAPI spec file. This is disabled by default. You
 
 - To enable it, set the `openapi.enabled` config option to `true`.
 
+- To override some fields in the generated spec, set the `openapi.overrides` config option to your changes. You can use dot notation to update specific nested fields. For instance, `['info.version' => '2.0.0']` will override the 'version` key in the 'info` object whenever generating.
+
 You can view the generated spec by visiting `public/docs/openapi.yaml` for `static` type, and `<your-app>/docs.openapi` for `laravel` type. This link will also be added to the sidebar of your docs.
 
 ## Customising the environment with `--env`
diff --git a/docs/index.md b/docs/index.md
@@ -12,6 +12,16 @@ Generate API documentation for humans from your Laravel/Lumen/[Dingo](https://gi
 ```eval_rst
 .. Tip:: Looking to document your Node.js APIs? Check out `Scribe for JS <https://github.com/knuckleswtf/scribe-js>`_.
 ```
+## Features
+- Pretty HTML documentation page, with included code samples and friendly text
+- Markdown source files that can be edited to modify docs
+- Extracts body parameters information from FormRequests
+- Safely calls API endpoints to generate sample responses, with authentication and other custom configuration supported
+- Supports generating responses from Transformers or Eloquent API Resources
+- Supports Postman collection and OpenAPI (Swagger) spec generation
+- Included UI components for additional styling
+- Easily customisable with custom views
+- Easily extensible with custom strategies
 
 ## Contents
 ```eval_rst
@@ -31,17 +41,6 @@ Generate API documentation for humans from your Laravel/Lumen/[Dingo](https://gi
    contributing
 ```
 
-## Features
-- Pretty HTML documentation page, with included code samples and friendly text
-- Markdown source files that can be edited to modify docs
-- Extracts body parameters information from FormRequests
-- Safely calls API endpoints to generate sample responses, with authentication and other custom configuration supported
-- Supports generating responses from Transformers or Eloquent API Resources
-- Supports Postman collection and OpenAPI (Swagger) spec generation
-- Included UI components for additional styling
-- Easily customisable with custom views
-- Easily extensible with custom strategies
-
 ## Installation
 PHP 7.2.5 and Laravel/Lumen 5.8 or higher are required.
 
diff --git a/src/Extracting/Strategies/Responses/ResponseCalls.php b/src/Extracting/Strategies/Responses/ResponseCalls.php
@@ -122,7 +122,7 @@ protected function prepareRequest(Route $route, array $rulesToApply, array $urlP
         $method = array_shift($routeMethods);
         $cookies = isset($rulesToApply['cookies']) ? $rulesToApply['cookies'] : [];
 
-        // Note that we initialise the request with the bodyPatams here
+        // Note that we initialise the request with the bodyParams here
         // and later still add them to the ParameterBag (`addBodyParameters`)
         // The first is so the body params get added to the request content
         // (where Laravel reads body from)
diff --git a/src/Writing/PostmanCollectionWriter.php b/src/Writing/PostmanCollectionWriter.php
@@ -43,7 +43,7 @@ public function __construct(Collection $routeGroups, $baseUrl)
         $this->auth = config('scribe.postman.auth');
     }
 
-    public function makePostmanCollection()
+    public function generatePostmanCollection()
     {
         $collection = [
             'variables' => [],
@@ -66,7 +66,7 @@ public function makePostmanCollection()
             $collection['auth'] = $this->auth;
         }
 
-        return json_encode($collection, JSON_PRETTY_PRINT);
+        return $collection;
     }
 
     protected function generateEndpointItem($route): array
diff --git a/src/Writing/Writer.php b/src/Writing/Writer.php
@@ -218,7 +218,14 @@ public function generatePostmanCollection(Collection $routes)
             ['routeGroups' => $routes, 'baseUrl' => $this->postmanBaseUrl]
         );
 
-        return $writer->makePostmanCollection();
+        $collection = $writer->generatePostmanCollection();
+        $overrides = $this->config->get('postman.overrides');
+        if (count($overrides)) {
+            foreach ($overrides as $key => $value) {
+                data_set($collection, $key, $value);
+            }
+        }
+        return json_encode($collection, JSON_PRETTY_PRINT);
     }
 
     public function generateOpenAPISpec(Collection $groupedEndpoints)
@@ -229,7 +236,14 @@ public function generateOpenAPISpec(Collection $groupedEndpoints)
             ['config' => $this->config]
         );
 
-        return Yaml::dump($writer->generateSpecContent($groupedEndpoints), 10, 4, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP);
+        $spec = $writer->generateSpecContent($groupedEndpoints);
+        $overrides = $this->config->get('openapi.overrides');
+        if (count($overrides)) {
+            foreach ($overrides as $key => $value) {
+                data_set($spec, $key, $value);
+            }
+        }
+        return Yaml::dump($spec, 10, 4, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP);
     }
 
     protected function performFinalTasksForLaravelType(): void
diff --git a/tests/Fixtures/collection-overridden.json b/tests/Fixtures/collection-overridden.json
@@ -0,0 +1,185 @@
+{
+    "variables": [],
+    "info": {
+        "name": "Custom API",
+        "_postman_id": "",
+        "description": "",
+        "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.0.0\/collection.json",
+        "version": "3.9.9"
+    },
+    "item": [
+        {
+            "name": "Group A",
+            "description": "",
+            "item": [
+                {
+                    "name": "Example title.",
+                    "request": {
+                        "url": {
+                            "protocol": "http",
+                            "host": "localhost",
+                            "path": "api\/withDescription",
+                            "query": [],
+                            "raw": "http:\/\/localhost\/api\/withDescription"
+                        },
+                        "method": "GET",
+                        "header": [
+                            {
+                                "key": "Content-Type",
+                                "value": "application\/json"
+                            },
+                            {
+                                "key": "Accept",
+                                "value": "application\/json"
+                            }
+                        ],
+                        "body": {
+                            "mode": "raw",
+                            "raw": "[]",
+                            "options": {
+                                "raw": {
+                                    "language": "json"
+                                }
+                            }
+                        },
+                        "description": "This will be the long description.\nIt can also be multiple lines long.",
+                        "response": []
+                    }
+                },
+                {
+                    "name": "api\/withResponseTag",
+                    "request": {
+                        "url": {
+                            "protocol": "http",
+                            "host": "localhost",
+                            "path": "api\/withResponseTag",
+                            "query": [],
+                            "raw": "http:\/\/localhost\/api\/withResponseTag"
+                        },
+                        "method": "GET",
+                        "header": [
+                            {
+                                "key": "Content-Type",
+                                "value": "application\/json"
+                            },
+                            {
+                                "key": "Accept",
+                                "value": "application\/json"
+                            }
+                        ],
+                        "body": {
+                            "mode": "raw",
+                            "raw": "[]",
+                            "options": {
+                                "raw": {
+                                    "language": "json"
+                                }
+                            }
+                        },
+                        "description": "",
+                        "response": []
+                    }
+                },
+                {
+                    "name": "Endpoint with body parameters.",
+                    "request": {
+                        "url": {
+                            "protocol": "http",
+                            "host": "localhost",
+                            "path": "api\/withBodyParameters",
+                            "query": [],
+                            "raw": "http:\/\/localhost\/api\/withBodyParameters"
+                        },
+                        "method": "POST",
+                        "header": [
+                            {
+                                "key": "Content-Type",
+                                "value": "application\/json"
+                            },
+                            {
+                                "key": "Accept",
+                                "value": "application\/json"
+                            }
+                        ],
+                        "body": {
+                            "mode": "raw",
+                            "raw": "{\n    \"user_id\": 9,\n    \"room_id\": \"consequatur\",\n    \"forever\": false,\n    \"another_one\": 11613.31890586,\n    \"yet_another_param\": {\n        \"name\": \"consequatur\"\n    },\n    \"even_more_param\": [\n        11613.31890586\n    ],\n    \"book\": {\n        \"name\": \"consequatur\",\n        \"author_id\": 17,\n        \"pages_count\": 17\n    },\n    \"ids\": [\n        17\n    ],\n    \"users\": [\n        {\n            \"first_name\": \"John\",\n            \"last_name\": \"Doe\"\n        }\n    ]\n}",
+                            "options": {
+                                "raw": {
+                                    "language": "json"
+                                }
+                            }
+                        },
+                        "description": "",
+                        "response": []
+                    }
+                },
+                {
+                    "name": "api\/withQueryParameters",
+                    "request": {
+                        "url": {
+                            "protocol": "http",
+                            "host": "localhost",
+                            "path": "api\/withQueryParameters",
+                            "query": [
+                                {
+                                    "key": "location_id",
+                                    "value": "consequatur",
+                                    "description": "The id of the location.",
+                                    "disabled": false
+                                },
+                                {
+                                    "key": "user_id",
+                                    "value": "me",
+                                    "description": "The id of the user.",
+                                    "disabled": false
+                                },
+                                {
+                                    "key": "page",
+                                    "value": "4",
+                                    "description": "The page number.",
+                                    "disabled": false
+                                },
+                                {
+                                    "key": "filters",
+                                    "value": "consequatur",
+                                    "description": "The filters.",
+                                    "disabled": false
+                                },
+                                {
+                                    "key": "url_encoded",
+                                    "value": "%2B+%5B%5D%26%3D",
+                                    "description": "Used for testing that URL parameters will be URL-encoded where needed.",
+                                    "disabled": false
+                                }
+                            ],
+                            "raw": "http:\/\/localhost\/api\/withQueryParameters?location_id=consequatur&user_id=me&page=4&filters=consequatur&url_encoded=%2B+%5B%5D%26%3D"
+                        },
+                        "method": "GET",
+                        "header": [
+                            {
+                                "key": "Content-Type",
+                                "value": "application\/json"
+                            },
+                            {
+                                "key": "Accept",
+                                "value": "application\/json"
+                            }
+                        ],
+                        "body": {
+                            "mode": "raw",
+                            "raw": "[]",
+                            "options": {
+                                "raw": {
+                                    "language": "json"
+                                }
+                            }
+                        },
+                        "description": "",
+                        "response": []
+                    }
+                }
+            ]
+        }
+    ]
+}
diff --git a/tests/Fixtures/openapi-overridden.yaml b/tests/Fixtures/openapi-overridden.yaml
diff --git a/tests/GenerateDocumentationTest.php b/tests/GenerateDocumentationTest.php
diff --git a/tests/Unit/PostmanCollectionWriterTest.php b/tests/Unit/PostmanCollectionWriterTest.php

Original file line number	Diff line number	Diff line change
`@@ -43,7 +43,7 @@ public function __construct(Collection $routeGroups, $baseUrl)`
`43`	`43`	`$this->auth = config('scribe.postman.auth');`
`44`	`44`	`}`
`45`	`45`
`46`		`- public function makePostmanCollection()`
	`46`	`+ public function generatePostmanCollection()`
`47`	`47`	`{`
`48`	`48`	`$collection = [`
`49`	`49`	`'variables' => [],`
`@@ -66,7 +66,7 @@ public function makePostmanCollection()`
`66`	`66`	`$collection['auth'] = $this->auth;`
`67`	`67`	`}`
`68`	`68`
`69`		`- return json_encode($collection, JSON_PRETTY_PRINT);`
	`69`	`+ return $collection;`
`70`	`70`	`}`
`71`	`71`
`72`	`72`	`protected function generateEndpointItem($route): array`