Update config comments

config/scribe.php

@@ -1,6 +1,130 @@
 <?php
 
 return [
+
+    /*
+     * The HTML <title> for the generated documentation. If this is empty, Scribe will infer it from config('app.name').
+     */
+    'title' => null,
+
+    /*
+     * A short description of your API.
+     */
+    'description' => '',
+
+
+    /*
+     * Tell Scribe what routes to generate documentation for.
+     * Each group contains rules defining which routes should be included ('match', 'include' and 'exclude' sections)
+     * and settings which should be applied to them ('apply' section).
+     */
+    'routes' => [
+        [
+            /*
+             * Specify conditions to determine what routes will be a part of this group.
+             * A route must fulfill ALL conditions to be included.
+             */
+            'match' => [
+                /*
+                 * Match only routes whose domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'.
+                 */
+                'domains' => ['*'],
+
+                /*
+                 * Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
+                 */
+                'prefixes' => ['*'],
+
+                /*
+                 * [Dingo router only] Match only routes registered under this version. Wildcards are not supported.
+                 */
+                'versions' => ['v1'],
+            ],
+
+            /*
+             * Include these routes even if they did not match the rules above.
+             * The route can be referenced by name or path here. Wildcards are supported.
+             */
+            'include' => [
+                // 'users.index', 'healthcheck*'
+            ],
+
+            /*
+             * Exclude these routes even if they matched the rules above.
+             * The route can be referenced by name or path here. Wildcards are supported.
+             */
+            'exclude' => [
+                // '/health', 'admin.*'
+            ],
+
+            /*
+             * Settings to be applied to all the matched routes in this group when generating documentation
+             */
+            'apply' => [
+                /*
+                 * Additional headers to be added to the example requests
+                 */
+                'headers' => [
+                    'Content-Type' => 'application/json',
+                    'Accept' => 'application/json',
+                ],
+
+                /*
+                 * If no @response or @transformer declarations are found for the route,
+                 * Scribe will try to get a sample response by attempting an API call.
+                 * Configure the settings for the API call here.
+                 */
+                'response_calls' => [
+                    /*
+                     * API calls will be made only for routes in this group matching these HTTP methods (GET, POST, etc).
+                     * List the methods here or use '*' to mean all methods. Leave empty to disable API calls.
+                     */
+                    'methods' => ['GET'],
+
+                    /*
+                     * Laravel config variables which should be set for the API call.
+                     * This is a good place to ensure that notifications, emails and other external services
+                     * are not triggered during the documentation API calls.
+                     * You can also create a `.env.docs` file and run the generate command with `--env docs`.
+                     */
+                    'config' => [
+                        'app.env' => 'documentation',
+                        // 'app.debug' => false,
+                    ],
+
+                    /*
+                     * Query parameters which should be sent with the API call.
+                     */
+                    'queryParams' => [
+                        // 'key' => 'value',
+                    ],
+
+                    /*
+                     * Body parameters which should be sent with the API call.
+                     */
+                    'bodyParams' => [
+                        // 'key' => 'value',
+                    ],
+
+                    /*
+                     * Files which should be sent with the API call.
+                     * Each value should be a valid path (absolute or relative to your project directory) to a file on this machine.
+                     */
+                    'fileParams' => [
+                        // 'key' => 'storage/app/image.png',
+                    ],
+
+                    /*
+                     * Cookies which should be sent with the API call.
+                     */
+                    'cookies' => [
+                        // 'name' => 'value'
+                    ],
+                ],
+            ],
+        ],
+    ],
+
     /*
      * The type of documentation output to generate.
      * - "static" will generate a static HTMl page in the /public/docs folder,
@@ -31,7 +155,7 @@ return [
 
         /*
          * URL path to use for the docs endpoint (if `add_routes` is true).
-         * By default, `/docs` opens the HTML page, and `/docs.json` downloads the Postman collection.
+         * By default, `/docs` opens the HTML page, `/docs.postman` opens the Postman collection, and `/docs.openapi` the OpenAPI spec.
          */
         'docs_url' => '/docs',
 
@@ -57,19 +181,19 @@ return [
         'enabled' => false,
 
         /*
-         * Set this to true if your API should be authenticated by default.
-         * You can then use @unauthenticated or @authenticated on individual endpoints to change their status.
+         * Set this to true if your API should be authenticated by default. If so, you must also set `enabled` (above) to true.
+         * You can then use @unauthenticated or @authenticated on individual endpoints to change their status from the default.
          */
         'default' => false,
 
         /*
          * Where is the auth value meant to be sent in a request?
-         * Options: query, body, query_or_body, basic, bearer, header (for custom header)
+         * Options: query, body, basic, bearer, header (for custom header)
          */
         'in' => 'bearer',
 
         /*
-         * The name of the parameter (eg token, key, apiKey) or header (eg Authorization, Api-Key).
+         * The name of the auth parameter (eg token, key, apiKey) or header (eg Authorization, Api-Key).
          */
         'name' => 'key',
 
@@ -82,7 +206,7 @@ return [
 
         /*
          * Placeholder your users will see for the auth parameter in the example requests.
-         * If this value is null, Scribe will use a random value.
+         * Set this to null if you want Scribe to use a random value as placeholder instead.
          */
         'placeholder' => '{YOUR_AUTH_KEY}',
 
@@ -106,9 +230,7 @@ INTRO
     /*
      * Example requests for each endpoint will be shown in each of these languages.
      * Supported options are: bash, javascript, php, python
-     * You can add a language of your own, but you must publish the package's views
-     * and define a corresponding view for it in the partials/example-requests directory.
-     * See https://scribe.readthedocs.io/en/latest/generating-documentation.html
+     * To add a language of your own, see https://scribe.readthedocs.io/en/latest/customization.html
      *
      */
     'example_languages' => [
@@ -117,25 +239,15 @@ INTRO
     ],
 
     /*
-     * The base URL to be used in examples.
-     * If this is null, Scribe will use the value of config('app.url').
+     * The base URL to be used in examples. If this is empty, Scribe will use the value of config('app.url').
      */
     'base_url' => null,
 
     /*
-     * The HTML <title> for the generated documentation, and the name of the generated Postman collection.
-     * If this is null, Scribe will infer it from config('app.name').
-     */
-    'title' => null,
-
-    'description' => '',
-
-    /*
-     * Generate a Postman collection in addition to HTML docs.
+     * Generate a Postman collection (v2.1.0) 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.add_routes` to true (above) will also add a route for the collection.
-     * Collection schema: https://schema.getpostman.com/json/collection/v2.0.0/collection.json
      */
     'postman' => [
         'enabled' => true,
@@ -149,7 +261,7 @@ INTRO
     ],
 
     /*
-     * Generate an OpenAPI spec file in addition to docs webpage.
+     * Generate an OpenAPI spec (v3.0.1) 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.
@@ -187,129 +299,6 @@ INTRO
      */
     'router' => 'laravel',
 
-    /*
-     * The routes for which documentation should be generated.
-     * Each group contains rules defining which routes should be included ('match', 'include' and 'exclude' sections)
-     * and settings which should be applied to them ('apply' section).
-     */
-    'routes' => [
-        [
-            /*
-             * Specify conditions to determine what routes will be parsed in this group.
-             * A route must fulfill ALL conditions to pass.
-             */
-            'match' => [
-                /*
-                 * Match only routes whose domains match this pattern (use * as a wildcard to match any characters). Example: 'api.*'.
-                 */
-                'domains' => ['*'],
-
-                /*
-                 * Match only routes whose paths match this pattern (use * as a wildcard to match any characters). Example: 'users/*'.
-                 */
-                'prefixes' => ['*'],
-
-                /*
-                 * (Dingo router only) Match only routes registered under this version.
-                 * Note that wildcards are not supported.
-                 */
-                'versions' => ['v1'],
-            ],
-
-            /*
-             * Include these routes when generating documentation, even if they did not match the rules above.
-             * The route can be referenced by name or path here. Wildcards are supported.
-             */
-            'include' => [
-                // 'users.index', 'healthcheck*'
-            ],
-
-            /*
-             * Exclude these routes when generating documentation, even if they matched the rules above.
-             * The route can be referenced by name or path here. Wildcards are supported.
-             */
-            'exclude' => [
-                // '/health', 'admin.*'
-            ],
-
-            /*
-             * Specify rules to be applied to all the routes in this group when generating documentation
-             */
-            'apply' => [
-                /*
-                 * Specify headers to be added to the example requests
-                 */
-                'headers' => [
-                    'Content-Type' => 'application/json',
-                    'Accept' => 'application/json',
-                ],
-
-                /*
-                 * If no @response or @transformer declarations are found for the route,
-                 * we'll try to get a sample response by attempting an API call.
-                 * Configure the settings for the API call here.
-                 */
-                'response_calls' => [
-                    /*
-                     * API calls will be made only for routes in this group matching these HTTP methods (GET, POST, etc).
-                     * List the methods here or use '*' to mean all methods. Leave empty to disable API calls.
-                     */
-                    'methods' => ['GET'],
-
-                    /*
-                     * Laravel config variables which should be set for the API call.
-                     * This is a good place to ensure that notifications, emails and other external services
-                     *  are not triggered during the documentation API calls.
-                     * You can also create a `.env.docs` file and run the generate command with `--env docs`.
-                     */
-                    'config' => [
-                        'app.env' => 'documentation',
-                        // 'app.debug' => false,
-                    ],
-
-                    /*
-                     * Cookies which should be sent with the API call.
-                     */
-                    'cookies' => [
-                        // 'name' => 'value'
-                    ],
-
-                    /*
-                     * Query parameters which should be sent with the API call.
-                     */
-                    'queryParams' => [
-                        // 'key' => 'value',
-                    ],
-
-                    /*
-                     * Body parameters which should be sent with the API call.
-                     */
-                    'bodyParams' => [
-                        // 'key' => 'value',
-                    ],
-
-                    /*
-                     * Files which should be sent with the API call.
-                     * Each value should be a valid path (absolute or relative to your project directory) to a file on this machine.
-                     */
-                    'fileParams' => [
-                        // 'key' => '/home/me/image.png',
-                    ],
-                ],
-            ],
-        ],
-    ],
-
-    /*
-     * Configure how responses are transformed using @transformer and @transformerCollection (requires league/fractal package)
-     */
-    'fractal' => [
-        /* If you are using a custom serializer with league/fractal, you can specify it here.
-         * Leave as null to use no serializer or return simple JSON.
-         */
-        'serializer' => null,
-    ],
-
     /*
      * If you would like the package to generate the same example values for parameters on each run,
      * set this to any number (eg. 1234)
@@ -318,7 +307,7 @@ INTRO
 
     /**
      * The strategies Scribe will use to extract information about your routes at each stage.
-     * If you write or install a custom strategy, add it here. Unless you know what you're doing, you shouldn't remove any of the default strategies.
+     * If you write or install a custom strategy, add it here.
      */
     'strategies' => [
         'metadata' => [
@@ -353,17 +342,26 @@ INTRO
     ],
 
     /*
-     * [Advanced usage] If you would like to customize how routes are matched beyond the route configuration you may
+     * Configure how responses are transformed using @transformer and @transformerCollection (requires league/fractal package)
+     */
+    'fractal' => [
+        /* If you are using a custom serializer with league/fractal, you can specify it here.
+         * Leave as null to use no serializer or return simple JSON.
+         */
+        'serializer' => null,
+    ],
+
+    /*
+     * [Advanced] If you would like to customize how routes are matched beyond the route configuration you may
      * declare your own implementation of RouteMatcherInterface
      *
      */
     'routeMatcher' => \Knuckles\Scribe\Matching\RouteMatcher::class,
 
     /**
-     * [Advanced usage] If one of your app's database drivers does not support transactions,
+     * [Advanced] If one of your app's database drivers does not support transactions,
      * docs generation (instantiating Eloquent models and making response calls) will likely fail.
-     * To avoid that, you can add the driver class name here.
-     * Be warned: that means all database changes will persist.
+     * To avoid that, you can add the driver class name here. Be warned: that means all database changes will persist.
      */
     'continue_without_database_transactions' => [],
 ];