openapi

Give any HTTP server an interactive API reference — the "try it" console included — by handing Register your *http.ServeMux and your OpenAPI document. The Stoplight Elements UI is embedded in the module, so a project ships only its generated spec: no per-project vendoring of the docs front-end.

mux := http.NewServeMux()

// mount your API handlers on mux…

if err := openapi.Register(mux, specYAML); err != nil {
    return err
}
// GET /openapi.yaml -> the spec
// GET /docs/        -> the Stoplight UI (try-it console)

Why a companion module

transport-openapi is a companion to go/transport, not part of its core. The Stoplight Elements distribution it embeds is ~2.4 MB (web-components.min.js + styles.min.css). Folding it into the transport core would add that to every server binary, even those that never serve API docs. Keeping it a separate import makes the cost opt-in: only a tool that mounts the docs pays for the embed.

• Same-origin by design. The spec and the docs UI are served from the same server as the API, so the "try it" console works without extra CORS setup.
• Secure by default. The docs/spec handlers are wrapped with go/transport's conservative security-header middleware (nosniff, X-Frame-Options: DENY, frame-ancestors 'none', Referrer-Policy: no-referrer). Customise or opt out.
• Framework-free. No go-tool-base, no Viper/Cobra — just go/transport, go/transit, cockroachdb/errors, and the standard library. A depfootprint_test.go guard keeps it that way.

Install

go get gitlab.com/phpboyscout/go/transport-openapi

Options

openapi.Register(mux, spec,
    openapi.WithSpecPath("/v1/openapi.yaml"),
    openapi.WithDocsPath("/v1/docs/"),
    openapi.WithTitle("Acme API v1"),
    openapi.WithSecurityHeaderOptions(/* transport/http SecurityHeadersOption… */),
    // openapi.WithoutSecurityHeaders(),
)

What it does not do

It serves bytes: no spec generation, no validation, no runtime reload, no caching, no auth on the docs routes, and no theming beyond the page title. The full list is in the limitations reference.

Compatibility

The versions each release is built and tested against are the ones in go.mod — currently go/transport v0.3.0 and go/transit v0.1.3. The version lines are not paired minor-for-minor: transport-openapi v0.1.x is built against go/transport v0.3.x. Both are pre-1.0, so upgrade them together if you pass WithSecurityHeaderOptions.

Documentation

Full guides: transport-openapi.go.phpboyscout.uk. API reference: pkg.go.dev.

License

See LICENSE. The embedded Stoplight Elements assets are vendored from stoplight.io/open-source/elements (Apache-2.0), pinned at v9.0.0.