Skip to content

Commit a04d177

Browse files
shalvahshalvah
authored
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
1 parent 22ef3f2 commit a04d177

File tree

6 files changed

+82
-11
lines changed

6 files changed

+82
-11
lines changed

‎config/scribe.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,10 @@
7373
'middleware' => [],
7474
],
7575

76+
'external' => [
77+
'html_attributes' => []
78+
],
79+
7680
'try_it_out' => [
7781
// Add a Try It Out button to your endpoints so consumers can test endpoints right from their browser.
7882
// Don't forget to enable CORS headers for your endpoints.

‎resources/views/external/elements.blade.php

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<!-- See https://github.com/stoplightio/elements/blob/main/docs/getting-started/elements/elements-options.md for config -->
2+
<!doctype html>
3+
<html lang="en">
4+
<head>
5+
<meta charset="utf-8">
6+
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
7+
<title>Elements in HTML</title>
8+
<!-- Embed elements Elements via Web Component -->
9+
<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
10+
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
11+
</head>
12+
<body>
13+
14+
<elements-api
15+
@foreach($htmlAttributes as $attribute => $value)
16+
{{-- Attributes specified first override later ones --}}
17+
{!! $attribute !!}="{!! $value !!}"
18+
@endforeach
19+
apiDescriptionUrl="{!! $metadata['openapi_spec_url'] !!}"
20+
router="hash"
21+
layout="sidebar"
22+
hideTryIt="{!! ($tryItOut['enabled'] ?? true) ? '' : 'true'!!}"
23+
logo="{!! $metadata['logo'] !!}"
24+
/>
25+
26+
</body>
27+
</html>

‎resources/views/external/rapidoc.blade.php

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,23 @@
1-
1+
<!-- See https://rapidocweb.com/api.html for options -->
22
<!doctype html> <!-- Important: must specify -->
33
<html>
44
<head>
55
<meta charset="utf-8"> <!-- Important: rapi-doc uses utf8 characters -->
66
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
77
</head>
88
<body>
9-
<rapi-doc spec-url="{!! $metadata['openapi_spec_url'] !!}"
10-
render-style="read"
11-
> </rapi-doc>
9+
<rapi-doc
10+
@foreach($htmlAttributes as $attribute => $value)
11+
{{-- Attributes specified first override later ones --}}
12+
{!! $attribute !!}="{!! $value !!}"
13+
@endforeach
14+
spec-url="{!! $metadata['openapi_spec_url'] !!}"
15+
render-style="read"
16+
allow-try="{!! ($tryItOut['enabled'] ?? true) ? 'true' : 'false'!!}"
17+
>
18+
@if($metadata['logo'])
19+
<img slot="logo" src="{!! $metadata['logo'] !!}"/>
20+
@endif
21+
</rapi-doc>
1222
</body>
1323
</html>

‎resources/views/external/scalar.blade.php

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
<html>
33
<head>
44
<title>{!! $metadata['title'] !!}</title>
5-
<meta charset="utf-8" />
5+
<meta charset="utf-8"/>
66
<meta
7-
name="viewport"
8-
content="width=device-width, initial-scale=1" />
7+
name="viewport"
8+
content="width=device-width, initial-scale=1"/>
99
<style>
1010
body {
1111
margin: 0;
@@ -15,8 +15,12 @@
1515
<body>
1616

1717
<script
18-
id="api-reference"
19-
data-url="{!! $metadata['openapi_spec_url'] !!}">
18+
id="api-reference"
19+
@foreach($htmlAttributes as $attribute => $value)
20+
{{-- Attributes specified first override later ones --}}
21+
{!! $attribute !!}="{!! $value !!}"
22+
@endforeach
23+
data-url="{!! $metadata['openapi_spec_url'] !!}">
2024
</script>
2125
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
2226
</body>

‎src/Tools/ConfigDiffer.php

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
namespace Knuckles\Scribe\Tools;
44

55
use Illuminate\Support\Str;
6+
use Symfony\Component\VarExporter\VarExporter;
67

78
class ConfigDiffer
89
{
@@ -59,8 +60,8 @@ protected function diffList(mixed $oldValue, array $value)
5960
return "changed to a list";
6061
}
6162

62-
$added = array_map(fn ($v) => "$v", array_diff($value, $oldValue));
63-
$removed = array_map(fn ($v) => "$v", array_diff($oldValue, $value));
63+
$added = array_map(fn ($v) => "$v", $this->subtractArraysFlat($value, $oldValue));
64+
$removed = array_map(fn ($v) => "$v", $this->subtractArraysFlat($oldValue, $value));
6465

6566
$diff = [];
6667
if (!empty($added)) {
@@ -72,4 +73,27 @@ protected function diffList(mixed $oldValue, array $value)
7273

7374
return empty($diff) ? "" : implode(": ", $diff);
7475
}
76+
77+
/**
78+
* Basically array_diff, but handling items which may also be arrays
79+
*/
80+
protected function subtractArraysFlat(array $a, array $b)
81+
{
82+
$mapped_a = array_map(function ($item) {
83+
if (is_array($item)) {
84+
return VarExporter::export($item);
85+
}
86+
87+
return $item;
88+
}, $a);
89+
$mapped_b = array_map(function ($item) {
90+
if (is_array($item)) {
91+
return VarExporter::export($item);
92+
}
93+
94+
return $item;
95+
}, $b);
96+
97+
return array_diff($mapped_a, $mapped_b);
98+
}
7599
}

‎src/Writing/ExternalHtmlWriter.php

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ public function generate(array $groupedEndpoints, string $sourceFolder, string $
1616
'metadata' => $this->getMetadata(),
1717
'baseUrl' => $this->baseUrl,
1818
'tryItOut' => $this->config->get('try_it_out'),
19+
'htmlAttributes' => $this->config->get('external.html_attributes', []),
1920
])->render();
2021

2122
if (!is_dir($destinationFolder)) {
@@ -44,4 +45,5 @@ public function getMetadata(): array
4445
"openapi_spec_url" => $openApiSpecUrl ?? null,
4546
];
4647
}
48+
4749
}

0 commit comments

Comments
 (0)