@michaelmishin/speclens 0.1.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 +94 -0
- package/dist/speclens.iife.js +3424 -0
- package/dist/speclens.iife.js.map +1 -0
- package/dist/speclens.js +30845 -0
- package/dist/speclens.js.map +1 -0
- package/package.json +54 -0
package/README.md
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# SpecLens
|
|
2
|
+
|
|
3
|
+
A modern, lightweight OpenAPI documentation renderer built as a web component. Drop it into any page via CDN — no build step required.
|
|
4
|
+
|
|
5
|
+
> **Status:** Early development (v0.1.0)
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- **Zero-dependency usage** — single script tag, works in any framework or plain HTML
|
|
10
|
+
- **Web component** — `<spec-lens>` custom element with Shadow DOM style isolation
|
|
11
|
+
- **Try It console** — live API request execution from the browser
|
|
12
|
+
- **Code samples** — generated snippets for cURL, JavaScript, Python, and more
|
|
13
|
+
- **Full-text search** — fast in-page search powered by MiniSearch
|
|
14
|
+
- **Light & dark themes** — auto-detects system preference, overridable via CSS custom properties
|
|
15
|
+
- **OpenAPI 3.x support** — parsed and validated by `@apidevtools/swagger-parser`
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
### CDN (recommended for quick start)
|
|
20
|
+
|
|
21
|
+
```html
|
|
22
|
+
<script src="https://unpkg.com/@michaelmishin/speclens/dist/speclens.iife.js"></script>
|
|
23
|
+
|
|
24
|
+
<spec-lens spec-url="/openapi.json"></spec-lens>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### ES Module
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
import '@michaelmishin/speclens';
|
|
31
|
+
|
|
32
|
+
// or via SpecLens.init() for programmatic control
|
|
33
|
+
import { SpecLens } from '@michaelmishin/speclens';
|
|
34
|
+
|
|
35
|
+
SpecLens.init('#docs', {
|
|
36
|
+
specUrl: '/openapi.json',
|
|
37
|
+
theme: 'auto', // 'light' | 'dark' | 'auto'
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### npm
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npm install @michaelmishin/speclens
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Theming
|
|
48
|
+
|
|
49
|
+
SpecLens exposes CSS custom properties for theming from outside the Shadow DOM:
|
|
50
|
+
|
|
51
|
+
```css
|
|
52
|
+
spec-lens {
|
|
53
|
+
--sl-color-primary: #6366f1;
|
|
54
|
+
--sl-color-bg: #ffffff;
|
|
55
|
+
--sl-color-text: #1a1a1a;
|
|
56
|
+
--sl-font-sans: 'Inter', system-ui, sans-serif;
|
|
57
|
+
--sl-font-mono: 'Fira Code', monospace;
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Development
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npm install
|
|
65
|
+
npm run dev # Vite dev server → http://localhost:5173
|
|
66
|
+
npm run build # Produces dist/speclens.js (ESM) + dist/speclens.iife.js (IIFE)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The demo page (`index.html`) loads the Petstore spec from `demo/petstore.json`.
|
|
70
|
+
|
|
71
|
+
## Architecture
|
|
72
|
+
|
|
73
|
+
| Path | Purpose |
|
|
74
|
+
|------|---------|
|
|
75
|
+
| `src/index.ts` | Entry point — registers `<spec-lens>`, exports `SpecLens.init()` |
|
|
76
|
+
| `src/spec-lens.ts` | Root orchestrator Lit component |
|
|
77
|
+
| `src/core/` | Parser, router (hash-based), full-text search, theme utilities |
|
|
78
|
+
| `src/components/` | Lit web components (layout, operation detail, schema, code samples, auth) |
|
|
79
|
+
| `src/styles/` | Design tokens, theme CSS, reset — authored as Lit `css` tagged templates |
|
|
80
|
+
| `src/shims/` | Browser shims for Node.js `util`/`path` (required by swagger-parser) |
|
|
81
|
+
|
|
82
|
+
## Stack
|
|
83
|
+
|
|
84
|
+
- [Lit v3](https://lit.dev) — web components
|
|
85
|
+
- [Vite](https://vitejs.dev) — build (library mode)
|
|
86
|
+
- [TypeScript](https://www.typescriptlang.org)
|
|
87
|
+
- [@apidevtools/swagger-parser](https://github.com/APIDevTools/swagger-parser) — spec parsing & validation
|
|
88
|
+
- [MiniSearch](https://lucaong.github.io/minisearch/) — full-text search
|
|
89
|
+
- [httpsnippet-lite](https://github.com/Kong/httpsnippet) — code sample generation
|
|
90
|
+
- [openapi-sampler](https://github.com/Redocly/openapi-sampler) — request body example generation
|
|
91
|
+
|
|
92
|
+
## License
|
|
93
|
+
|
|
94
|
+
MIT
|