fix: transform scribe.openapi.format to scribe.openapi.json

knuckleswtf · Mar 5, 2024 · 08900a6 · 08900a6
1 parent 22a11a6
commit 08900a6
Show file tree

Hide file tree

Showing 9 changed files with 25 additions and 19 deletions.
diff --git a/config/scribe.php b/config/scribe.php
@@ -154,12 +154,10 @@
     // For 'static' docs, the collection will be generated to public/docs/openapi.yaml.
     // For 'laravel' docs, it will be generated to storage/app/scribe/openapi.yaml.
     // Setting `laravel.add_routes` to true (above) will also add a route for the spec.
+    // If the json format is chosen, the file will be saved as openapi.json
     'openapi' => [
         'enabled' => true,
 
-        // The output format for the spec, either 'yaml' or 'json'.
-        'format' => 'yaml',
-
         'overrides' => [
             // 'info.version' => '2.0.0',
         ],

diff --git a/routes/laravel.php b/routes/laravel.php
@@ -16,6 +16,6 @@
         })->name('scribe.postman');
 
         Route::get("$prefix.openapi", function () {
-            return response()->file(Storage::disk('local')->path('scribe/openapi.' . config('scribe.openapi.format')));
+            return response()->file(Storage::disk('local')->path('scribe/openapi.' . (config('scribe.openapi.json', false) ? 'json' : 'yaml')));
         })->name('scribe.openapi');
     });
diff --git a/routes/lumen.php b/routes/lumen.php
@@ -18,6 +18,6 @@
         return new JsonResponse(Storage::disk('local')->get('scribe/collection.json'), json: true);
     })->name('scribe.postman');
     $router->get("$prefix.openapi", function () {
-        return response()->file(Storage::disk('local')->path('scribe/openapi.' . config('scribe.openapi.format')));
+        return response()->file(Storage::disk('local')->path('scribe/openapi.' . (config('scribe.openapi.json', false) ? 'json' : 'yaml')));
     })->name('scribe.openapi');
 });
diff --git a/src/Writing/ExternalHtmlWriter.php b/src/Writing/ExternalHtmlWriter.php
@@ -33,7 +33,8 @@ public function getMetadata(): array
             $postmanCollectionUrl = "{$this->assetPathPrefix}collection.json";
         }
         if ($this->config->get('openapi.enabled', false)) {
-            $openApiSpecUrl = "{$this->assetPathPrefix}openapi." . config('scribe.openapi.format');
+            $openApiSpecUrl = $this->assetPathPrefix . OpenAPISpecWriter::getSpecFileName();
+
         }
         return [
             'title' => $this->config->get('title') ?: config('app.name', '') . ' Documentation',

diff --git a/src/Writing/HtmlWriter.php b/src/Writing/HtmlWriter.php
@@ -117,8 +117,8 @@ public function getMetadata(): array
             $postmanCollectionUrl = "{$this->assetPathPrefix}collection.json";
         }
         if ($this->config->get('openapi.enabled', false)) {
-            $links[] = "<a href=\"{$this->assetPathPrefix}openapi.".config('scribe.openapi.format')."\">".u::trans("scribe::links.openapi")."</a>";
-            $openApiSpecUrl = "{$this->assetPathPrefix}openapi.".config('scribe.openapi.format');
+            $links[] = "<a href=\"{$this->assetPathPrefix}".OpenAPISpecWriter::getSpecFileName()."\">".u::trans("scribe::links.openapi")."</a>";
+            $openApiSpecUrl = $this->assetPathPrefix.OpenAPISpecWriter::getSpecFileName();
         }
 
         $auth = $this->config->get('auth');

diff --git a/src/Writing/OpenAPISpecWriter.php b/src/Writing/OpenAPISpecWriter.php
@@ -249,7 +249,6 @@ protected function generateEndpointRequestBodySpec(OutputEndpointData $endpoint)
             }
 
             $body['content'][$contentType]['schema'] = $schema;
-
         }
 
         // return object rather than empty array, so can get properly serialised as object
@@ -528,7 +527,7 @@ protected function operationId(OutputEndpointData $endpoint): string
         if ($endpoint->metadata->title) return preg_replace('/[^\w+]/', '', Str::camel($endpoint->metadata->title));
 
         $parts = preg_split('/[^\w+]/', $endpoint->uri, -1, PREG_SPLIT_NO_EMPTY);
-        return Str::lower($endpoint->httpMethods[0]) . join('', array_map(fn($part) => ucfirst($part), $parts));
+        return Str::lower($endpoint->httpMethods[0]) . join('', array_map(fn ($part) => ucfirst($part), $parts));
     }
 
     /**
@@ -586,4 +585,14 @@ public function generateSchemaForValue(mixed $value, OutputEndpointData $endpoin
 
         return $schema;
     }
+
+    /**
+     * Get the filename for the OpenAPI spec file, with a .yaml or .json extension following the configuration
+     *
+     * @return string
+     */
+    public static function getSpecFileName(): string
+    {
+        return 'openapi.' . (config('scribe.openapi.json', false)  ? 'json' : 'yaml');
+    }
 }
diff --git a/src/Writing/Writer.php b/src/Writing/Writer.php
@@ -96,19 +96,17 @@ protected function writeOpenAPISpec(array $parsedRoutes): void
 
             $spec = $this->generateOpenAPISpec($parsedRoutes);
 
-            if (config('scribe.openapi.format') === 'json') {
-                $fileName = "openapi.json";
+            if (config('scribe.openapi.json', false)) {
                 $fileContent = json_encode($spec, JSON_PRETTY_PRINT);
             } else {
-                $fileName = "openapi.yaml";
                 $fileContent = Yaml::dump($spec, 20, 2, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP);
             }
 
             if ($this->isStatic) {
-                $specPath = "{$this->staticTypeOutputPath}/{$fileName}";
+                $specPath = "{$this->staticTypeOutputPath}/" . OpenAPISpecWriter::getSpecFileName();
                 file_put_contents($specPath, $fileContent);
             } else {
-                $outputPath = $this->paths->outputPath($fileName);
+                $outputPath = $this->paths->outputPath(OpenAPISpecWriter::getSpecFileName());
                 Storage::disk('local')->put($outputPath, $fileContent);
                 $specPath = Storage::disk('local')->path($outputPath);
             }
@@ -186,8 +184,8 @@ protected function performFinalTasksForLaravelType(): void
         $contents = preg_replace('#href="\.\./docs/css/(.+?)"#', 'href="{{ asset("' . $this->laravelAssetsPath . '/css/$1") }}"', $contents);
         $contents = preg_replace('#src="\.\./docs/(js|images)/(.+?)"#', 'src="{{ asset("' . $this->laravelAssetsPath . '/$1/$2") }}"', $contents);
         $contents = str_replace('href="../docs/collection.json"', 'href="{{ route("' . $this->paths->outputPath('postman', '.') . '") }}"', $contents);
-        $contents = str_replace('href="../docs/openapi.' . config('scribe.openapi.format') . '"', 'href="{{ route("' . $this->paths->outputPath('openapi', '.') . '") }}"', $contents);
-        $contents = str_replace('url="../docs/openapi.' . config('scribe.openapi.format') . '"', 'url="{{ route("' . $this->paths->outputPath('openapi', '.') . '") }}"', $contents);
+        $contents = str_replace('href="../docs'.OpenAPISpecWriter::getSpecFileName().'"', 'href="{{ route("' . $this->paths->outputPath('openapi', '.') . '") }}"', $contents);
+        $contents = str_replace('url="../docs'.OpenAPISpecWriter::getSpecFileName().'"', 'url="{{ route("' . $this->paths->outputPath('openapi', '.') . '") }}"', $contents);
 
         file_put_contents("$this->laravelTypeOutputPath/index.blade.php", $contents);
     }

diff --git a/tests/GenerateDocumentation/BehavioursTest.php b/tests/GenerateDocumentation/BehavioursTest.php
@@ -118,7 +118,7 @@ public function calls_afterGenerating_hook()
             'html' => realpath('public/docs/index.html'),
             'blade' => null,
             'postman' => realpath('public/docs/collection.json') ?: null,
-            'openapi' => realpath('public/docs/openapi.'.config('scribe.openapi.format')) ?: null,
+            'openapi' => realpath('public/docs/openapi.'.(config('scribe.openapi.json') ? 'json' : 'yaml')) ?: null,
             'assets' => [
                 'js' => realpath('public/docs/js'),
                 'css' => realpath('public/docs/css'),

diff --git a/tests/GenerateDocumentation/OutputTest.php b/tests/GenerateDocumentation/OutputTest.php
@@ -244,7 +244,7 @@ public function generated_openapi_spec_file_is_correct_json()
 
         $this->setConfig([
             'openapi.enabled' => true,
-            'openapi.format' => 'json',
+            'openapi.json' => true,
             'openapi.overrides' => [
                 'info.version' => '3.9.9',
             ],