Switch to response_calls.auth rather than auth.use_value

config/scribe.php

@@ -61,13 +61,6 @@ return [
          */
         'name' => 'token',
 
-        /*
-         * The value of the parameter to be used by Scribe to authenticate response calls.
-         * This will NOT be included in the generated documentation.
-         * If this value is null, Scribe will use a random value.
-         */
-        'use_value' => env('SCRIBE_AUTH_KEY'),
-
         /*
          * Any extra authentication-related info for your users. For instance, you can describe how to find or generate their auth credentials.
          * Markdown and HTML are supported.
@@ -266,6 +259,12 @@ INTRO
                         // 'app.debug' => false,
                     ],
 
+                    /*
+                     * The value of the auth parameter (described in your auth section above) to be used by Scribe to authenticate response calls.
+                     * If this value is empty, Scribe will use a random value.
+                     */
+                    'auth' => env('SCRIBE_AUTH_KEY'),
+
                     /*
                      * Cookies which should be sent with the API call.
                      */

docs/config.md

@@ -100,8 +100,6 @@ Here are the available settings:
 
 - `name`: The name of the parameter (eg `token`, `key`, `apiKey`) or header (eg `Authorization`, `Api-Key`). When `in` is set to `bearer` or `basic`, this value will be ignored, and the header used will be `Authorization`.
 
-- `use_value`: The value of the parameter to be used by Scribe to authenticate response calls. This will **not** be included in the generated documentation. If this value is null, Scribe will use a random value.
-
 - `extra_info`: Any extra authentication-related info for your users. For instance, you can describe how to find or generate their auth credentials. Markdown and HTML are supported. This will be included in the `Authentication` section.
 
 ### `strategies`

docs/documenting/documenting-api-information.md

@@ -18,7 +18,6 @@ Here's how you'd configure auth with a query parameter named `apiKey`:
         'enabled' => true,
         'in' => 'query',
         'name' => 'apiKey',
-        'use_value' => env('SCRIBE_API_KEY'),
         'extra_info' => 'You can retrieve your key by going to settings and clicking <b>Generate API key</b>.',
     ],
 ```
@@ -33,7 +32,6 @@ Here's an example with a bearer token (also applies to basic auth, if you change
         'enabled' => true,
         'in' => 'bearer',
         'name' => 'hahaha', // <--- This value is ignored for bearer and basic auth
-        'use_value' => env('SCRIBE_AUTH_KEY'),
         'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
     ],
 ```
@@ -46,14 +44,13 @@ And here's an example with a custom header:
         'enabled' => true,
         'in' => 'header',
         'name' => 'Api-Key', // <--- The name of the header
-        'use_value' => env('SCRIBE_AUTH_KEY'),
         'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
     ],
 ```
 
 You can set whatever you want as the `extra_info`. A good idea would be to tell your users where to get their auth key. 
 
-The `use_value` field is only used by Scribe for response calls. It won't be included in the generated output or examples.
+You can also specify the value Scribe should use for response calls by setting `response_calls.auth`. This value will only be used to authenticate calls to endpoints marked as authenticated; it won't be included in the generated output or examples.
 
 For more information, see the [reference documentation on the auth section](../config.html#auth).
 

docs/documenting/documenting-endpoint-responses.md

@@ -135,6 +135,8 @@ The configuration for response calls is located in the `apply.response_calls` se
 .. Tip:: You can also modify the environment directly by using a :code:`.env.docs` file and running :code:`scribe:generate` with :code:`--env docs`.
 ```
 
+- If you have authenticated endpoints, you can use `response_calls.auth` to authenticate your response calls. Set it to the value of the auth parameter. Scribe combines this with the information in your `auth` section to authenticate your requests. If this value is empty, Scribe will use a random value. 
+
 - By default, the package will generate dummy values for your documented query, body and file parameters and send in the request. If you specified example values using `@bodyParam` or `@queryParam`, those will be used instead. You can configure additional parameters or overwrite the existing ones for the request in the `response_calls.queryParams`, `response_calls.bodyParams`, and `response_calls.fileParams` sections. For file parameters, each value should be a valid absolute path to a file on the machine.
 
 ```eval_rst

src/Extracting/Generator.php

@@ -9,6 +9,7 @@ use Illuminate\Support\Arr;
 use Illuminate\Support\Str;
 use Knuckles\Scribe\Extracting\Strategies\Strategy;
 use Knuckles\Scribe\Tools\DocumentationConfig;
+use Knuckles\Scribe\Tools\ConsoleOutputUtils as c;
 use Knuckles\Scribe\Tools\Utils as u;
 use ReflectionClass;
 use ReflectionFunctionAbstract;
@@ -316,6 +317,13 @@ class Generator
         }
         $token = $faker->shuffle('abcdefghkvaZVDPE1864563');
         $valueToUse = $this->config->get('auth.use_value');
+
+        if ($valueToUse) {
+            c::deprecated('the `auth.use_value` config item', 'change this to `response_calls.auth`');
+        } else {
+            $this->config->get('response_calls.auth');
+        }
+
         switch ($strategy) {
             case 'query':
             case 'query_or_body':

src/Tools/ConsoleOutputUtils.php

@@ -21,7 +21,7 @@ class ConsoleOutputUtils
             ->only();
     }
 
-    public static function deprecated($feature, $shouldUse = null, $link = null)
+    public static function deprecated($feature, $should = null, $link = null)
     {
         if (!self::$clara) {
             self::bootstrapOutput(new ConsoleOutput);
@@ -29,7 +29,7 @@ class ConsoleOutputUtils
 
         $message = "You're using $feature. This is deprecated and will be removed in the next major version.";
         if ($shouldUse) {
-            $message .= "\nYou should use $shouldUse instead.";
+            $message .= "\nYou should $should instead.";
         }
         if ($link) {
             $message .= " See $link for details";

src/Writing/PostmanCollectionWriter.php

@@ -44,7 +44,7 @@ class PostmanCollectionWriter
         $this->auth = config('scribe.postman.auth');
 
         if ($this->auth) {
-            c::deprecated('the `postman.auth` config key', 'the `postman.overrides` feature');
+            c::deprecated('the `postman.auth` config item', 'use the `postman.overrides` feature');
         }
     }
 
@@ -53,7 +53,7 @@ class PostmanCollectionWriter
         $description = config('scribe.postman.description', '');
 
         if ($description) {
-            c::deprecated('the `postman.description` config key', 'the `description` key');
+            c::deprecated('the `postman.description` config item', 'use the `description` item');
         } else {
             $description = config('scribe.description', '');
         }