Merge pull request #84 from vr00/feature/configurable-display-value

Add ability to replace random token string in generated code examples

config/scribe.php

@@ -68,6 +68,12 @@ return [
          */
         'use_value' => env('SCRIBE_AUTH_KEY'),
 
+        /*
+         * Placeholder your users will see for the auth parameter in the example requests.
+         * If this value is null, Scribe will use a random value.
+         */
+        'placeholder' => '{YOUR_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.

docs/config.md

@@ -102,6 +102,8 @@ Here are the available settings:
 
 - `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.
 
+- `placeholder`: Placeholder your users will see for the auth parameter in the example requests. If this is empty, Scribe will generate a realistic-looking auth token instead. Defaults to: "{YOUR_AUTH_KEY}".
+
 - `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

@@ -19,6 +19,7 @@ Here's how you'd configure auth with a query parameter named `apiKey`:
         'in' => 'query',
         'name' => 'apiKey',
         'use_value' => env('SCRIBE_API_KEY'),
+        'placeholder' => 'YOUR-API-KEY',
         'extra_info' => 'You can retrieve your key by going to settings and clicking <b>Generate API key</b>.',
     ],
 ```
@@ -34,6 +35,7 @@ Here's an example with a bearer token (also applies to basic auth, if you change
         'in' => 'bearer',
         'name' => 'hahaha', // <--- This value is ignored for bearer and basic auth
         'use_value' => env('SCRIBE_AUTH_KEY'),
+        'placeholder' => '{ACCESS_TOKEN}',
         'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
     ],
 ```
@@ -47,6 +49,7 @@ And here's an example with a custom header:
         'in' => 'header',
         'name' => 'Api-Key', // <--- The name of the header
         'use_value' => env('SCRIBE_AUTH_KEY'),
+        'placeholder' => 'YOUR-API-KEY',
         'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
     ],
 ```
@@ -54,6 +57,7 @@ And here's an example with a custom header:
 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.
+The `placeholder` is opposite of `use_value`. It will be used only as a placeholder in the generated example requests.
 
 For more information, see the [reference documentation on the auth section](../config.html#auth).
 

src/Extracting/Generator.php

@@ -333,13 +333,14 @@ class Generator
         }
         $token = $faker->shuffle('abcdefghkvaZVDPE1864563');
         $valueToUse = $this->config->get('auth.use_value');
+        $valueToDisplay = $this->config->get('auth.placeholder');
         switch ($strategy) {
             case 'query':
             case 'query_or_body':
                 $parsedRoute['auth'] = "cleanQueryParameters.$parameterName.".($valueToUse ?: $token);
                 $parsedRoute['queryParameters'][$parameterName] = [
                     'name' => $parameterName,
-                    'value' => $token,
+                    'value' => $valueToDisplay ?:$token,
                     'description' => '',
                     'required' => true,
                 ];
@@ -349,22 +350,22 @@ class Generator
                 $parsedRoute['bodyParameters'][$parameterName] = [
                     'name' => $parameterName,
                     'type' => 'string',
-                    'value' => $token,
+                    'value' => $valueToDisplay ?: $token,
                     'description' => '',
                     'required' => true,
                 ];
                 break;
             case 'bearer':
                 $parsedRoute['auth'] = "headers.Authorization.Bearer ".($valueToUse ?: $token);
-                $parsedRoute['headers']['Authorization'] = "Bearer $token";
+                $parsedRoute['headers']['Authorization'] = "Bearer ".($valueToDisplay ?: $token);
                 break;
             case 'basic':
                 $parsedRoute['auth'] = "headers.Authorization.Basic ".($valueToUse ?: base64_encode($token));
-                $parsedRoute['headers']['Authorization'] = "Basic ".base64_encode($token);
+                $parsedRoute['headers']['Authorization'] = "Basic ".($valueToDisplay ?: base64_encode($token));
                 break;
             case 'header':
                 $parsedRoute['auth'] = "headers.$parameterName.".($valueToUse ?: $token);
-                $parsedRoute['headers'][$parameterName] = $token;
+                $parsedRoute['headers'][$parameterName] = $valueToDisplay ?: $token;
                 break;
         }