go-docless

go-docless is a modular toolkit for turning Go HTTP handlers into OpenAPI 3 specifications and shipping the docs with zero framework lock-in. Route sampling, handler analysis, static UIs, and framework adapters are provided as separate packages so you only import what you need.

• Language: Go 1.22+
• CLI: docless (generated when you install the root module)
• License: Docless Community License v1.0

Packages & Use Cases

Package	Import Path	Purpose
Core engine	github.com/webasoo/go-docless/core	Route discovery, handler metadata, OpenAPI JSON generation
Swagger UI	github.com/webasoo/go-docless/swagger	Embedded Swagger UI assets served via net/http
Redoc UI	github.com/webasoo/go-docless/redoc	Embedded Redoc viewer served via net/http
Fiber adapter	github.com/webasoo/go-docless/fiber-swagger	Wraps Swagger handler for Fiber apps; auto-loads openapi.json
Chi adapter	github.com/webasoo/go-docless/chi-swagger	Mounts Swagger UI on Chi routers
Gin adapter	github.com/webasoo/go-docless/gin-swagger	Mounts Swagger UI on Gin routers

Install only what you require; Go will fetch shared dependencies automatically.

Installation

# Install the CLI (provides `docless`)
go install github.com/webasoo/go-docless@latest

# Add any adapter or helper package to your project
go get github.com/webasoo/go-docless/fiber-swagger

Generating Documentation

The CLI exposes a single sub-command:

# generate <module-root>/openapi.json
cd /path/to/your/project
recipient@host$ docless generate

Key flags:

-o <path>        # write to a custom file (relative paths resolved from module root)
-route <dir>     # add extra directories to scan for routes (repeatable)
-skip <prefix>   # ignore URLs with the given prefix (repeatable)

For automation you can wire the CLI into Go’s generation workflow:

//go:generate go run github.com/webasoo/go-docless generate
package yourpackage

Running go generate ./... will refresh openapi.json.

Serving the UI

Once the spec exists, add an adapter that fits your stack.

Standard Library

if err := swagger.RegisterFile("openapi.json"); err != nil {
    log.Fatal(err)
}
if err := redoc.RegisterFile("openapi.json"); err != nil {
    log.Fatal(err)
}
log.Fatal(http.ListenAndServe(":8080", nil))

Fiber

app := fiber.New()
// register your handlers first …
if err := fiberswagger.Register(app); err != nil {
    log.Fatal(err)
}
app.Listen(":8080")

Chi / Gin

if err := chiswagger.RegisterFile(router, "openapi.json"); err != nil {
    log.Fatal(err)
}
if err := ginswagger.RegisterFile(router, "openapi.json"); err != nil {
    log.Fatal(err)
}

Examples

The examples/ directory contains runnable samples that demonstrate:

• examples/http – standard library server that serves Swagger + Redoc
• examples/fiber – Fiber server wired to the adapter

Run them after generating docs:

GOCACHE=$(pwd)/.gocache go run ./examples/http

Development Notes

• Go 1.22 or newer is required.
• Static assets are vendored via go:generate go generate ./swagger ./redoc.
• Tests (TODO) will cover route discovery, CLI, and adapters.

License

This project is distributed under the Docless Community License v1.0. Non-commercial usage is permitted. Commercial use or public forks require written approval from the author.

For commercial licensing enquiries, email amin@webasoo.com.