* New config option to allow more customisation on the servers added …

…to the open api yaml
knuckleswtf · Sep 13, 2023 · c55659e · c55659e
1 parent b32959d
commit c55659e
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 6 deletions.
diff --git a/config/scribe.php b/config/scribe.php
@@ -22,6 +22,16 @@
      */
     'base_url' => null,
 
+    /*
+     * An array of servers available for the generated docs.
+     * Overrides base_url when generating the servers list for the openapi.yaml file.
+     */
+    'servers' => [
+//        [
+//            'url' => null,
+//            'description' => null,
+//        ],
+    ],
     /*
      * Tell Scribe what routes to generate documentation for.
      * Each group contains rules defining which routes should be included ('match', 'include' and 'exclude' sections)

diff --git a/src/Commands/GenerateDocumentation.php b/src/Commands/GenerateDocumentation.php
@@ -163,7 +163,7 @@ protected function upgradeConfigFileIfNeeded(): void
             $upgrader = Upgrader::ofConfigFile("config/{$this->configName}.php", __DIR__ . '/../../config/scribe.php')
                 ->dontTouch(
                     'routes', 'example_languages', 'database_connections_to_transact', 'strategies', 'laravel.middleware',
-                    'postman.overrides', 'openapi.overrides', 'groups', 'examples.models_source'
+                    'postman.overrides', 'openapi.overrides', 'groups', 'examples.models_source', 'servers',
                 );
             $changes = $upgrader->dryRun();
             if (!empty($changes)) {

diff --git a/src/Writing/OpenAPISpecWriter.php b/src/Writing/OpenAPISpecWriter.php
@@ -43,11 +43,7 @@ public function generateSpecContent(array $groupedEndpoints): array
                 'description' => $this->config->get('description', ''),
                 'version' => '1.0.0',
             ],
-            'servers' => [
-                [
-                    'url' => rtrim($this->config->get('base_url') ?? config('app.url'), '/'),
-                ],
-            ],
+            'servers' => $this->generateServers(),
             'paths' => $this->generatePathsSpec($groupedEndpoints),
             'tags' => array_values(array_map(function (array $group) {
                 return [
@@ -58,6 +54,20 @@ public function generateSpecContent(array $groupedEndpoints): array
         ], $this->generateSecurityPartialSpec());
     }
 
+    protected function generateServers(): array
+    {
+        $servers = $this->config->get('servers', []);
+        if ($servers) {
+            return $servers;
+        }
+
+        return [
+            [
+                'url' => rtrim($this->config->get('base_url') ?? config('app.url'), '/'),
+            ],
+        ];
+    }
+
     /**
      * @param array[] $groupedEndpoints
      *

diff --git a/tests/Unit/OpenAPISpecWriterTest.php b/tests/Unit/OpenAPISpecWriterTest.php
@@ -22,6 +22,16 @@ class OpenAPISpecWriterTest extends TestCase
         'title' => 'My Testy Testes API',
         'description' => 'All about testy testes.',
         'base_url' => 'http://api.api.dev',
+        'servers' => [
+            [
+                'url' => 'http://api.api.dev',
+                'description' => 'TheSideProjectAPI (Development)',
+            ],
+            [
+                'url' => 'http://api.api.prod',
+                'description' => 'TheSideProjectAPI (Production)',
+            ],
+        ]
     ];
 
     /** @test */
@@ -30,6 +40,9 @@ public function follows_correct_spec_structure()
         $endpointData1 = $this->createMockEndpointData();
         $endpointData2 = $this->createMockEndpointData();
         $groups = [$this->createGroup([$endpointData1, $endpointData2])];
+        // Remove the servers key, so we can confirm backwards compatibility with "base_url" config option
+        $ephemeralConfig = $this->config;
+        unset($this->config['servers']);
 
         $results = $this->generate($groups);
 
@@ -40,6 +53,14 @@ public function follows_correct_spec_structure()
         $this->assertEquals($this->config['base_url'], $results['servers'][0]['url']);
         $this->assertIsArray($results['paths']);
         $this->assertGreaterThan(0, count($results['paths']));
+
+        // Reset the config, so we can now test the new "servers" config option
+        $this->config = $ephemeralConfig;
+        $results = $this->generate($groups);
+        $this->assertEquals($this->config['servers'][0]['url'], $results['servers'][0]['url']);
+        $this->assertEquals($this->config['servers'][0]['description'], $results['servers'][0]['description']);
+        $this->assertEquals($this->config['servers'][1]['url'], $results['servers'][1]['url']);
+        $this->assertEquals($this->config['servers'][1]['description'], $results['servers'][1]['description']);
     }
 
     /** @test */