@braydenyang/fdoc
v0.1.25
Published
Embeddable OpenAPI 3.x documentation & debug UI
Downloads
2,186
Readme
fdoc
Embeddable OpenAPI 3.x documentation & debug UI.
Supports OpenAPI 3.0 / 3.1 / 3.2. Works as a standalone HTML file, an npm package, or a server-side handler (Gin, etc.).
Usage
1. CDN (script tag)
The quickest way — no build step required.
<!doctype html>
<html>
<head>
<link rel="stylesheet" href="https://unpkg.com/@braydenyang/[email protected]/dist/lib/style.css">
<style>html, body { margin: 0; height: 100% }</style>
</head>
<body>
<div id="fdoc" style="height: 100vh"></div>
<script src="https://unpkg.com/@braydenyang/[email protected]/dist/lib/fdoc.iife.js"></script>
<script>
Fdoc.mount('#fdoc', { url: '/openapi.json' })
</script>
</body>
</html>url is optional. If omitted, the UI starts empty and the user can import a spec manually.
2. npm (ES module)
npm install @braydenyang/fdocimport { mount } from '@braydenyang/fdoc'
import '@braydenyang/fdoc/style.css'
const unmount = mount('#fdoc', { url: '/openapi.json' })
// later, to tear down:
unmount()mount accepts a CSS selector string or an HTMLElement.
3. Gin (Go)
Copy docs/gin/fdoc.go into your project and use fdoc.Handler to serve the docs page.
package main
import (
"github.com/gin-gonic/gin"
"yourmodule/fdoc"
)
func main() {
r := gin.Default()
// Serve the OpenAPI spec
r.GET("/openapi.json", func(c *gin.Context) {
c.File("./openapi.json")
})
// Serve the docs UI — spec is loaded automatically
r.GET("/docs", gin.WrapF(fdoc.Handler("/openapi.json")))
r.Run(":8080")
}To customise the page title:
r.GET("/docs", gin.WrapF(fdoc.HandlerWithOpts(fdoc.Opts{
SpecURL: "/openapi.json",
Title: "My API Docs",
})))fdoc.go has no external dependencies beyond the Go standard library.
API
mount(el, options?)
| Parameter | Type | Description |
|-----------|------|-------------|
| el | string \| HTMLElement | Mount target. A CSS selector or DOM element. |
| options.url | string (optional) | URL of the OpenAPI JSON to fetch and load on mount. |
Returns an unmount function.
Build
# Development server
pnpm dev
# Library build (dist/lib/)
pnpm build:lib
# Standalone single-file HTML build (dist/cdn/)
pnpm build -- --mode cdn