* auth.extra_info now propagates through to the security schema as description (#727)

Author: ProjectZero4

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 => [],
         };

tests/Unit/OpenAPISpecWriterTest.php

@@ -80,15 +80,22 @@ 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);
 
         $this->assertCount(1, $results['components']['securitySchemes']);
         $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']);