External UI improvements (#780)

* Support TryItOut and logo in rapi-doc external view * Add Stoplight `elements` external view * Allow passing of custom HTML attributes to external UIs * Fix config:diff
knuckleswtf · Dec 29, 2023 · a04d177 · a04d177
1 parent 22ef3f2
commit a04d177
Show file tree

Hide file tree

Showing 6 changed files with 82 additions and 11 deletions.
diff --git a/config/scribe.php b/config/scribe.php
@@ -73,6 +73,10 @@
         'middleware' => [],
     ],
 
+    'external' => [
+        'html_attributes' => []
+    ],
+
     'try_it_out' => [
         // Add a Try It Out button to your endpoints so consumers can test endpoints right from their browser.
         // Don't forget to enable CORS headers for your endpoints.

diff --git a/resources/views/external/elements.blade.php b/resources/views/external/elements.blade.php
@@ -0,0 +1,27 @@
+<!-- See https://github.com/stoplightio/elements/blob/main/docs/getting-started/elements/elements-options.md for config -->
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <title>Elements in HTML</title>
+    <!-- Embed elements Elements via Web Component -->
+    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
+</head>
+<body>
+
+<elements-api
+@foreach($htmlAttributes as $attribute => $value)
+    {{-- Attributes specified first override later ones --}}
+    {!! $attribute !!}="{!! $value !!}"
+@endforeach
+    apiDescriptionUrl="{!! $metadata['openapi_spec_url'] !!}"
+    router="hash"
+    layout="sidebar"
+    hideTryIt="{!! ($tryItOut['enabled'] ?? true) ? '' : 'true'!!}"
+    logo="{!! $metadata['logo'] !!}"
+/>
+
+</body>
+</html>
diff --git a/resources/views/external/rapidoc.blade.php b/resources/views/external/rapidoc.blade.php
@@ -1,13 +1,23 @@
-
+<!-- See https://rapidocweb.com/api.html for options -->
 <!doctype html> <!-- Important: must specify -->
 <html>
 <head>
     <meta charset="utf-8"> <!-- Important: rapi-doc uses utf8 characters -->
     <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
 </head>
 <body>
-<rapi-doc spec-url="{!! $metadata['openapi_spec_url'] !!}"
-          render-style="read"
-> </rapi-doc>
+<rapi-doc
+@foreach($htmlAttributes as $attribute => $value)
+    {{-- Attributes specified first override later ones --}}
+    {!! $attribute !!}="{!! $value !!}"
+@endforeach
+    spec-url="{!! $metadata['openapi_spec_url'] !!}"
+    render-style="read"
+    allow-try="{!! ($tryItOut['enabled'] ?? true) ? 'true' : 'false'!!}"
+>
+    @if($metadata['logo'])
+        <img slot="logo" src="{!! $metadata['logo'] !!}"/>
+    @endif
+</rapi-doc>
 </body>
 </html>
diff --git a/resources/views/external/scalar.blade.php b/resources/views/external/scalar.blade.php
@@ -2,10 +2,10 @@
 <html>
 <head>
     <title>{!! $metadata['title'] !!}</title>
-    <meta charset="utf-8" />
+    <meta charset="utf-8"/>
     <meta
-            name="viewport"
-            content="width=device-width, initial-scale=1" />
+        name="viewport"
+        content="width=device-width, initial-scale=1"/>
     <style>
         body {
             margin: 0;
@@ -15,8 +15,12 @@
 <body>
 
 <script
-        id="api-reference"
-        data-url="{!! $metadata['openapi_spec_url'] !!}">
+    id="api-reference"
+@foreach($htmlAttributes as $attribute => $value)
+    {{-- Attributes specified first override later ones --}}
+    {!! $attribute !!}="{!! $value !!}"
+@endforeach
+    data-url="{!! $metadata['openapi_spec_url'] !!}">
 </script>
 <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
 </body>

diff --git a/src/Tools/ConfigDiffer.php b/src/Tools/ConfigDiffer.php
@@ -3,6 +3,7 @@
 namespace Knuckles\Scribe\Tools;
 
 use Illuminate\Support\Str;
+use Symfony\Component\VarExporter\VarExporter;
 
 class ConfigDiffer
 {
@@ -59,8 +60,8 @@ protected function diffList(mixed $oldValue, array $value)
             return "changed to a list";
         }
 
-        $added = array_map(fn ($v) => "$v", array_diff($value, $oldValue));
-        $removed = array_map(fn ($v) => "$v", array_diff($oldValue, $value));
+        $added = array_map(fn ($v) => "$v", $this->subtractArraysFlat($value, $oldValue));
+        $removed = array_map(fn ($v) => "$v", $this->subtractArraysFlat($oldValue, $value));
 
         $diff = [];
         if (!empty($added)) {
@@ -72,4 +73,27 @@ protected function diffList(mixed $oldValue, array $value)
 
         return empty($diff) ? "" : implode(": ", $diff);
     }
+
+    /**
+     * Basically array_diff, but handling items which may also be arrays
+     */
+    protected function subtractArraysFlat(array $a, array $b)
+    {
+        $mapped_a = array_map(function ($item) {
+            if (is_array($item)) {
+                return VarExporter::export($item);
+            }
+
+            return $item;
+        }, $a);
+        $mapped_b = array_map(function ($item) {
+            if (is_array($item)) {
+                return VarExporter::export($item);
+            }
+
+            return $item;
+        }, $b);
+
+        return array_diff($mapped_a, $mapped_b);
+    }
 }
diff --git a/src/Writing/ExternalHtmlWriter.php b/src/Writing/ExternalHtmlWriter.php
@@ -16,6 +16,7 @@ public function generate(array $groupedEndpoints, string $sourceFolder, string $
             'metadata' => $this->getMetadata(),
             'baseUrl' => $this->baseUrl,
             'tryItOut' => $this->config->get('try_it_out'),
+            'htmlAttributes' => $this->config->get('external.html_attributes', []),
         ])->render();
 
         if (!is_dir($destinationFolder)) {
@@ -44,4 +45,5 @@ public function getMetadata(): array
             "openapi_spec_url" => $openApiSpecUrl ?? null,
         ];
     }
+
 }