@michaelmishin/speclens 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +55 -3
- package/dist/speclens.iife.js +176 -42
- package/dist/speclens.iife.js.map +1 -1
- package/dist/speclens.js +242 -24
- package/dist/speclens.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
A modern, lightweight OpenAPI documentation renderer built as a web component. Drop it into any page via CDN — no build step required.
|
|
4
4
|
|
|
5
|
-
> **
|
|
5
|
+
> **Version:** 0.2.0
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
9
9
|
- **Zero-dependency usage** — single script tag, works in any framework or plain HTML
|
|
10
10
|
- **Web component** — `<spec-lens>` custom element with Shadow DOM style isolation
|
|
11
|
-
- **Try It console** — live API request execution
|
|
12
|
-
- **Code samples** — generated snippets for cURL, JavaScript, Python, and
|
|
11
|
+
- **Try It console** — live API request execution with support for JSON, `multipart/form-data`, and `application/x-www-form-urlencoded` bodies
|
|
12
|
+
- **Code samples** — generated snippets for cURL, JavaScript, Python, Node.js, Go, Java, PHP, Ruby, and C#
|
|
13
13
|
- **Full-text search** — fast in-page search powered by MiniSearch
|
|
14
14
|
- **Light & dark themes** — auto-detects system preference, overridable via CSS custom properties
|
|
15
15
|
- **OpenAPI 3.x support** — parsed and validated by `@apidevtools/swagger-parser`
|
|
@@ -44,6 +44,58 @@ SpecLens.init('#docs', {
|
|
|
44
44
|
npm install @michaelmishin/speclens
|
|
45
45
|
```
|
|
46
46
|
|
|
47
|
+
## Customization
|
|
48
|
+
|
|
49
|
+
### Layout Modes
|
|
50
|
+
|
|
51
|
+
Use the `layout` attribute to control how SpecLens integrates with the surrounding page.
|
|
52
|
+
|
|
53
|
+
| Value | Behavior |
|
|
54
|
+
|-------|----------|
|
|
55
|
+
| `page` (default) | Renders its own sticky header with title, Authorize, and theme toggle. Best for standalone CDN use. |
|
|
56
|
+
| `embed` | Suppresses the header entirely. The sidebar starts at the top of the container, and an Authorize button appears at the bottom of the sidebar when the API has security schemes. Use this when embedding inside an existing app that already has a navbar. |
|
|
57
|
+
|
|
58
|
+
```html
|
|
59
|
+
<!-- Standalone page -->
|
|
60
|
+
<spec-lens layout="page" spec-url="/openapi.json"></spec-lens>
|
|
61
|
+
|
|
62
|
+
<!-- Inside an existing app with its own navbar -->
|
|
63
|
+
<spec-lens layout="embed" spec-url="/openapi.json"></spec-lens>
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Named Slots (page mode)
|
|
67
|
+
|
|
68
|
+
In `layout="page"` mode, the header exposes two named slots for customization:
|
|
69
|
+
|
|
70
|
+
| Slot | Replaces |
|
|
71
|
+
|------|----------|
|
|
72
|
+
| `logo` | The API title + version badge in the header |
|
|
73
|
+
| `header-actions` | Additional items in the header action row, placed before the theme toggle |
|
|
74
|
+
|
|
75
|
+
```html
|
|
76
|
+
<spec-lens spec-url="/openapi.json">
|
|
77
|
+
<!-- Replace the title/version with your own logo -->
|
|
78
|
+
<img slot="logo" src="/my-logo.svg" alt="My API" height="28" />
|
|
79
|
+
|
|
80
|
+
<!-- Add extra nav items next to the theme toggle -->
|
|
81
|
+
<a slot="header-actions" href="/changelog">Changelog</a>
|
|
82
|
+
</spec-lens>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Programmatic Theme Control
|
|
86
|
+
|
|
87
|
+
In `layout="embed"` mode the theme toggle button is not visible. Use the `setTheme()` method or the `theme` attribute to control it from the host app:
|
|
88
|
+
|
|
89
|
+
```js
|
|
90
|
+
const docs = document.querySelector('spec-lens');
|
|
91
|
+
|
|
92
|
+
// Programmatic method
|
|
93
|
+
docs.setTheme('dark'); // 'light' | 'dark' | 'auto'
|
|
94
|
+
|
|
95
|
+
// Or set the attribute
|
|
96
|
+
docs.setAttribute('theme', 'dark');
|
|
97
|
+
```
|
|
98
|
+
|
|
47
99
|
## Theming
|
|
48
100
|
|
|
49
101
|
SpecLens exposes CSS custom properties for theming from outside the Shadow DOM:
|