Add ability to customise textual description of API authentication

config/scribe.php

@@ -30,6 +30,38 @@ return [
         'middleware' => [],
     ],
 
+    /*
+     * How is your API authenticated? This information will be used in the displayed docs, generated examples and response calls.
+     */
+    'auth' => [
+        /*
+         * Set this to true if your API is authenticated.
+         */
+        'enabled' => 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)
+         */
+        'in' => 'bearer',
+
+        /*
+         * The name of the parameter (eg token, key, apiKey) or header (eg Authorization, Api-Key).
+         */
+        'name' => 'token',
+
+        /*
+         * The value of the parameter. This will NOT be part of the generated documentation.
+         * Use it to easily auth response calls by this package.
+         */
+        'value' => env('SCRIBE_API_KEY'),
+
+        /*
+         * Short text describing to your users where to find (or generate) their auth key.
+         */
+        'how_to_fetch' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
+    ],
+
     /*
      * Example requests for each endpoint will be shown in each of these languages.
      * Supported options are: bash, javascript, php, python

resources/views/authentication.blade.php

@@ -1,3 +1,7 @@
-# Authentication
+# Authenticating requests
 
+@if(!$isAuthed)
 This API is not authenticated.
+@else
+{!! $text !!}
+@endif

src/Writing/Writer.php

@@ -235,7 +235,42 @@ class Writer
 
     protected function writeAuthMarkdownFile(): void
     {
-        $authMarkdown = view('scribe::authentication');
+        $isAuthed = $this->config->get('auth.enabled', false);
+        $text = '';
+
+        if ($isAuthed) {
+            $strategy = $this->config->get('auth.in');
+            $parameterName = $this->config->get('auth.name');
+            $text = Arr::random([
+                "This API is authenticated by sending ",
+                "To authenticate requests, include ",
+                "Authenticate requests to this API's endpoints by sending ",
+            ]);
+            switch ($strategy) {
+                case 'query':
+                    $text .= "a query parameter **`$parameterName`** in the request.";
+                    break;
+                case 'body':
+                    $text .= "a parameter **`$parameterName`** in the body of the request.";
+                    break;
+                case 'query_or_body':
+                    $text .= "a parameter **`$parameterName`** either in the query string or in the request body.";
+                    break;
+                case 'bearer':
+                    $text .= "an **`Authorization`** header with the value **`\"Bearer {your-token}\"`**.";
+                    break;
+                case 'basic':
+                    $text .= "an **`Authorization`** header in the form **`\"Basic {credentials}\"`**. The value of `{credentials}` should be your username/id and your password, joined with a colon (:), and then base64-encoded.";
+                    break;
+                case 'header':
+                    $text .= "a **`$parameterName`** header with the value **`\"{your-token}\"`**.";
+                    break;
+            }
+            $howToFetch = $this->config->get('auth.how_to_fetch', '');
+            $text .= " $howToFetch";
+        }
+
+        $authMarkdown = view('scribe::authentication', ['isAuthed' => $isAuthed, 'text' => $text]);
         $this->writeFile($this->sourceOutputPath . '/source/authentication.md', $authMarkdown);
     }