From e501a919f148a76cdb5ada7535bd853ed65c9fa1 Mon Sep 17 00:00:00 2001
From: Josh Capener <josh@joshcapener.co.uk>
Date: Thu, 14 Sep 2023 16:17:16 +0100
Subject: [PATCH] * auth.extra_info now propagates through to the security
 schema as description (#727)

---
 src/Writing/OpenAPISpecWriter.php    |  6 +++---
 tests/Unit/OpenAPISpecWriterTest.php | 21 ++++++++++++++++++---
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/src/Writing/OpenAPISpecWriter.php b/src/Writing/OpenAPISpecWriter.php
index 0857bfe6..509c01f0 100644
--- a/src/Writing/OpenAPISpecWriter.php
+++ b/src/Writing/OpenAPISpecWriter.php
@@ -403,18 +403,18 @@ protected function generateSecurityPartialSpec(): array
 
         $location = $this->config->get('auth.in');
         $parameterName = $this->config->get('auth.name');
-
+        $description = $this->config->get('auth.extra_info');
         $scheme = match ($location) {
             'query', 'header' => [
                 'type' => 'apiKey',
                 'name' => $parameterName,
                 'in' => $location,
-                'description' => '',
+                'description' => $description,
             ],
             'bearer', 'basic' => [
                 'type' => 'http',
                 'scheme' => $location,
-                'description' => '',
+                'description' => $description,
             ],
             default => [],
         };
diff --git a/tests/Unit/OpenAPISpecWriterTest.php b/tests/Unit/OpenAPISpecWriterTest.php
index 52fa6cf2..41990675 100644
--- a/tests/Unit/OpenAPISpecWriterTest.php
+++ b/tests/Unit/OpenAPISpecWriterTest.php
@@ -80,8 +80,14 @@ public function adds_authentication_details_correctly_as_security_info()
         $endpointData1 = $this->createMockEndpointData(['uri' => 'path1', 'httpMethods' => ['GET'], 'metadata.authenticated' => true]);
         $endpointData2 = $this->createMockEndpointData(['uri' => 'path1', 'httpMethods' => ['POST'], 'metadata.authenticated' => false]);
         $groups = [$this->createGroup([$endpointData1, $endpointData2])];
-
-        $config = array_merge($this->config, ['auth' => ['enabled' => true, 'in' => 'bearer']]);
+        $extraInfo = "When stuck trying to authenticate, have a coffee!";
+        $config = array_merge($this->config, [
+            'auth' => [
+                'enabled' => true,
+                'in' => 'bearer',
+                'extra_info' => $extraInfo,
+            ],
+        ]);
         $writer = new OpenAPISpecWriter(new DocumentationConfig($config));
         $results = $writer->generateSpecContent($groups);
 
@@ -89,6 +95,7 @@ public function adds_authentication_details_correctly_as_security_info()
         $this->assertArrayHasKey('default', $results['components']['securitySchemes']);
         $this->assertEquals('http', $results['components']['securitySchemes']['default']['type']);
         $this->assertEquals('bearer', $results['components']['securitySchemes']['default']['scheme']);
+        $this->assertEquals($extraInfo, $results['components']['securitySchemes']['default']['description']);
         $this->assertCount(1, $results['security']);
         $this->assertCount(1, $results['security'][0]);
         $this->assertArrayHasKey('default', $results['security'][0]);
@@ -97,13 +104,21 @@ public function adds_authentication_details_correctly_as_security_info()
         $this->assertCount(0, $results['paths']['/path1']['post']['security']);
 
         // Next try: auth with a query parameter
-        $config = array_merge($this->config, ['auth' => ['enabled' => true, 'in' => 'query', 'name' => 'token']]);
+        $config = array_merge($this->config, [
+            'auth' => [
+                'enabled' => true,
+                'in' => 'query',
+                'name' => 'token',
+                'extra_info' => $extraInfo,
+            ],
+        ]);
         $writer = new OpenAPISpecWriter(new DocumentationConfig($config));
         $results = $writer->generateSpecContent($groups);
 
         $this->assertCount(1, $results['components']['securitySchemes']);
         $this->assertArrayHasKey('default', $results['components']['securitySchemes']);
         $this->assertEquals('apiKey', $results['components']['securitySchemes']['default']['type']);
+        $this->assertEquals($extraInfo, $results['components']['securitySchemes']['default']['description']);
         $this->assertEquals($config['auth']['name'], $results['components']['securitySchemes']['default']['name']);
         $this->assertEquals('query', $results['components']['securitySchemes']['default']['in']);
         $this->assertCount(1, $results['security']);