@braydenyang/fdoc 0.1.0 → 0.1.2
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 +120 -0
- package/dist/lib/fdoc +43757 -831
- package/dist/lib/fdoc.iife +3513 -0
- package/dist/lib/style.css +1 -1
- package/package.json +9 -3
package/README.md
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# fdoc
|
|
2
|
+
|
|
3
|
+
Embeddable OpenAPI 3.x documentation & debug UI.
|
|
4
|
+
|
|
5
|
+
Supports OpenAPI 3.0 / 3.1 / 3.2. Works as a standalone HTML file, an npm package, or a server-side handler (Gin, etc.).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
### 1. CDN (script tag)
|
|
12
|
+
|
|
13
|
+
The quickest way — no build step required.
|
|
14
|
+
|
|
15
|
+
```html
|
|
16
|
+
<!doctype html>
|
|
17
|
+
<html>
|
|
18
|
+
<head>
|
|
19
|
+
<link rel="stylesheet" href="https://unpkg.com/@braydenyang/fdoc@0.1.0/dist/lib/style.css">
|
|
20
|
+
<style>html, body { margin: 0; height: 100% }</style>
|
|
21
|
+
</head>
|
|
22
|
+
<body>
|
|
23
|
+
<div id="fdoc" style="height: 100vh"></div>
|
|
24
|
+
<script src="https://unpkg.com/@braydenyang/fdoc@0.1.0/dist/lib/fdoc.iife.js"></script>
|
|
25
|
+
<script>
|
|
26
|
+
Fdoc.mount('#fdoc', { url: '/openapi.json' })
|
|
27
|
+
</script>
|
|
28
|
+
</body>
|
|
29
|
+
</html>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`url` is optional. If omitted, the UI starts empty and the user can import a spec manually.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
### 2. npm (ES module)
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npm install @braydenyang/fdoc
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { mount } from '@braydenyang/fdoc'
|
|
44
|
+
import '@braydenyang/fdoc/style.css'
|
|
45
|
+
|
|
46
|
+
const unmount = mount('#fdoc', { url: '/openapi.json' })
|
|
47
|
+
|
|
48
|
+
// later, to tear down:
|
|
49
|
+
unmount()
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`mount` accepts a CSS selector string or an `HTMLElement`.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
### 3. Gin (Go)
|
|
57
|
+
|
|
58
|
+
Copy [`docs/gin/fdoc.go`](docs/gin/fdoc.go) into your project and use `fdoc.Handler` to serve the docs page.
|
|
59
|
+
|
|
60
|
+
```go
|
|
61
|
+
package main
|
|
62
|
+
|
|
63
|
+
import (
|
|
64
|
+
"github.com/gin-gonic/gin"
|
|
65
|
+
"yourmodule/fdoc"
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
func main() {
|
|
69
|
+
r := gin.Default()
|
|
70
|
+
|
|
71
|
+
// Serve the OpenAPI spec
|
|
72
|
+
r.GET("/openapi.json", func(c *gin.Context) {
|
|
73
|
+
c.File("./openapi.json")
|
|
74
|
+
})
|
|
75
|
+
|
|
76
|
+
// Serve the docs UI — spec is loaded automatically
|
|
77
|
+
r.GET("/docs", gin.WrapF(fdoc.Handler("/openapi.json")))
|
|
78
|
+
|
|
79
|
+
r.Run(":8080")
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
To customise the page title:
|
|
84
|
+
|
|
85
|
+
```go
|
|
86
|
+
r.GET("/docs", gin.WrapF(fdoc.HandlerWithOpts(fdoc.Opts{
|
|
87
|
+
SpecURL: "/openapi.json",
|
|
88
|
+
Title: "My API Docs",
|
|
89
|
+
})))
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`fdoc.go` has no external dependencies beyond the Go standard library.
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## API
|
|
97
|
+
|
|
98
|
+
### `mount(el, options?)`
|
|
99
|
+
|
|
100
|
+
| Parameter | Type | Description |
|
|
101
|
+
|-----------|------|-------------|
|
|
102
|
+
| `el` | `string \| HTMLElement` | Mount target. A CSS selector or DOM element. |
|
|
103
|
+
| `options.url` | `string` (optional) | URL of the OpenAPI JSON to fetch and load on mount. |
|
|
104
|
+
|
|
105
|
+
Returns an `unmount` function.
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## Build
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
# Development server
|
|
113
|
+
pnpm dev
|
|
114
|
+
|
|
115
|
+
# Library build (dist/lib/)
|
|
116
|
+
pnpm build:lib
|
|
117
|
+
|
|
118
|
+
# Standalone single-file HTML build (dist/cdn/)
|
|
119
|
+
pnpm build -- --mode cdn
|
|
120
|
+
```
|