@braydenyang/fdoc

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/fdoc@0.1.3/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/fdoc@0.1.3/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/fdoc

import { 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?)

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