http-swagger

http-swagger is a small net/http middleware that turns a swag-generated OpenAPI spec into a live Swagger UI page and JSON endpoint, letting any Go HTTP server expose interactive API documentation without shipping or hosting the Swagger UI assets separately. A single Handler() call, wired into any net/http-compatible router, serves the Swagger UI HTML shell, its bundled JS/CSS assets, and the generated doc.json from one mount point.

Configuration follows Go’s functional-options pattern: URL, DocExpansion, DeepLinking, PersistAuthorization, Layout, ShowExtensions, and DefaultModelsExpandDepth cover the common UI knobs, while BeforeScript/AfterScript and UIConfig give an escape hatch for injecting custom Swagger UI JavaScript and plugins. It ships as the v2 module path (github.com/swaggo/http-swagger/v2) of the original swaggo/http-swagger package, depending on swaggo/swag for the underlying spec lookup and swaggo/files/v2 for the embedded UI assets.

What You Get

• A drop-in http.HandlerFunc via Handler() that serves the Swagger UI page, its static assets, and the generated doc.json from one route
• A functional-options Config (URL, DocExpansion, DeepLinking, PersistAuthorization, Layout, ShowExtensions, DefaultModelsExpandDepth) for tuning the rendered UI
• BeforeScript/AfterScript and Plugins/UIConfig hooks for injecting custom Swagger UI JavaScript and plugins
• Bundled Swagger UI static assets via the sibling swaggo/files/v2 module, so no CDN or separate asset hosting is required
• Ready-made go-chi and gorilla/mux example apps showing the full wiring end to end

Common Use Cases

• Exposing interactive /swagger/* documentation for a Go REST API built with net/http, chi, gorilla/mux, or any compatible router
• Pairing with swag init to keep hand-written Swagger annotations in sync with a live, browsable API explorer
• Customizing the rendered Swagger UI (default model expansion, deep linking, persisted auth) per environment via Config options
• Injecting custom onComplete JavaScript to rewrite the spec’s host, scheme, or basePath at runtime behind a reverse proxy

Under The Hood

Architecture The package is a single file (swagger.go, ~350 lines) exposing an idiomatic Go functional-options pattern: a Config struct plus configFns …func(*Config) build up the middleware’s behavior, and Handler() closes over a parsed html/template.New(“swagger_index.html”) template to return a plain http.HandlerFunc, so all state lives in the closure rather than an instantiated struct. A compiled regex extracts the trailing path segment from r.RequestURI, and a filepath.Ext-based switch on that segment decides the response: index.html renders the embedded template, doc.json defers to swag.ReadDoc(config.InstanceName) to fetch the caller’s already-registered OpenAPI spec, and every other path falls through to http.FileServer(http.FS(swaggerFiles.FS)) backed by the sibling swaggo/files/v2 module’s embedded Swagger UI assets. There is no layering beyond this single request-dispatch function, so the embedded asset filesystem and the WrapHandler package-level variable are the two load-bearing pieces the whole package depends on.

Tech Stack Go module github.com/swaggo/http-swagger/v2 (go.mod requires Go 1.17+), depending on github.com/swaggo/swag v1.8.1 for OpenAPI spec registration/lookup and github.com/swaggo/files/v2 v2.0.2 for embedded Swagger UI static assets; github.com/stretchr/testify v1.7.0 is a test-only dependency. The runtime surface is otherwise pure standard library (net/http, html/template, path/filepath, net/url, regexp), with no external web framework dependency — the two bundled examples wire it into go-chi and gorilla/mux routers. CI runs via GitHub Actions across a matrix of recent Go versions with coverage uploaded to Codecov; there is no separate build step beyond go build/go test.

Code Quality swagger_test.go holds a dozen tests built on httptest.NewRecorder()/httptest.NewRequest() and testify/assert, covering the main routing branches (index redirect, doc.json success and failure, static asset serving, custom InstanceName lookups). Error handling favors returning HTTP error status codes over panics, but two paths are intentionally silent — template execution errors in Handler() and errors from the static file server are both ignored rather than logged. Naming follows conventional exported-Go style with doc-comments on every exported symbol; there is no linter configuration or vet step in CI, so quality enforcement rests on the test suite alone.

API Design The public surface is a single Handler(…func(*Config)) http.HandlerFunc built from a small set of composable functional options (URL, DocExpansion, DeepLinking, Plugins, UIConfig, BeforeScript/AfterScript, Layout, DefaultModelsExpandDepth, ShowExtensions), so adopting it takes one route registration in any net/http-compatible router — the bundled go-chi and gorilla/mux examples show the entire integration in well under 20 lines. Documentation lives in the README and per-option doc-comments rather than a generated walkthrough. The BeforeScript/AfterScript/UIConfig hooks are a pragmatic but low-level escape hatch — raw JavaScript strings templated directly into the page — trading type safety for flexibility that Swagger UI’s own JS configuration doesn’t otherwise expose through Go types.