transport-openapi¶

Serve an OpenAPI spec and an interactive Stoplight Elements docs site from one Register call.

Hand Register your *http.ServeMux and your OpenAPI document, and your server gains a live API reference — with a "try it" console — at /docs/, plus the raw spec at /openapi.yaml. The Stoplight Elements UI is embedded in the module, so a project ships only its generated spec.

mux := http.NewServeMux()
// mount your API handlers…
if err := openapi.Register(mux, specYAML); err != nil {
    return err
}

Highlights¶

• One call. Register(mux, spec, opts...) mounts both the spec and the docs UI.
• Same-origin. Spec and docs are served from the same server as the API, so the try-it console needs no CORS setup.
• Secure by default. Docs/spec handlers are wrapped with go/transport's conservative security-header middleware; customise or opt out.
• Opt-in weight. A companion to go/transport — the ~2.4 MB embedded UI never bloats a server that doesn't serve docs.

What this does not do¶

It serves bytes. It does not generate your OpenAPI document, validate it, reload it without a restart, cache it, authenticate anyone, or let you theme the docs page beyond its title. Limitations is the full list — worth reading before you design around this.

Where next¶

• Tutorial — serve API docs from your own server: a runnable server, its spec, and a working try-it console, in about fifteen minutes.
• How-to — customise paths & title, security headers, serve on a go/transport server.
• Reference — options, routes, limitations, and the API on pkg.go.dev.
• Explanation — why a companion module, same-origin docs by design.

Part of the phpboyscout Go toolkit — a companion to go/transport.

Further reading¶

The blog carries a curated route through this subject: Building a web service in Go collects everything written about it, ordered so you can start at the beginning rather than newest-first.