Documentation
¶
Overview ¶
Package swagger serves a local Swagger UI page and pinned static assets for an application-owned OpenAPI specification URL. It supports OpenAPI 3.2 through Swagger UI 5.34.0; the specification remains a separate endpoint.
Register the returned router.Handler explicitly. Register the exact page path as well as the wildcard to avoid a router-generated slash redirect:
endpoint, err := swagger.Handler("/docs", "/openapi.json")
if err != nil {
log.Fatal(err)
}
routes := router.New()
routes.Get("/docs", endpoint)
routes.Get("/docs/{path...}", endpoint)
For the root base path "/", register "/{path...}". A reverse proxy prefix must be included in the explicit base path; no forwarded headers are trusted. Protect documentation routes with the application's normal middleware when the API is private. The browser fetches the specification and any referenced schemas; this package performs no network requests or lifecycle work.
The initializer is an external same-origin script, with no inline scripts or CDN dependencies. CSP must allow same-origin scripts, Swagger UI's inline styles and data images, and connections to the chosen specification and API origins. Remote validation and query-string configuration are disabled. The handler neither sets nor weakens an application's CSP headers.
Dependencies are the standard library and http/router. The embedded upstream JavaScript and CSS are distributed under Apache-2.0; assets/PROVENANCE records their version, source, checksums, and compatibility evidence. There is no npm installation or third-party Go dependency at build or runtime.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
func Handler(basePath, specificationURL string, configure ...BuilderFunc) (router.Handler, error)
Handler constructs an immutable Swagger UI endpoint without registering routes or fetching the specification. basePath is an absolute, clean URL path without a trailing slash (except "/"); its segments use unreserved ASCII characters. specificationURL must be nonempty: HTTP(S), root-relative, and relative URLs are accepted, but credentials, fragments, scheme-relative URLs, whitespace, and backslashes are rejected. Relative URLs resolve against basePath + "/", consistently for both page paths; request host and forwarding headers are ignored. Invalid configuration returns an error before a handler is published.
The page is served at basePath and basePath + "/". Only GET and HEAD are accepted. Static assets are pinned locally; the initializer disables the remote validator and query-string configuration. Application middleware still owns access control and CSP. Allow same-origin scripts, inline styles used by Swagger UI, and connections to the specification/API origins. No inline script is needed. Callbacks run synchronously once in order, including for invalid inputs; nil callbacks panic. The completed handler supports concurrent requests.
Example:
endpoint, err := swagger.Handler("/docs", "/openapi.json")
if err != nil {
log.Fatal(err)
}
routes := router.New()
routes.Get("/docs", endpoint)
routes.Get("/docs/{path...}", endpoint)
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder configures one documentation page during Handler construction. Retaining the draft does not permit changes to the published handler.
Example:
configure := func(page *swagger.Builder) {
page.Title("Billing API")
}
_, err := swagger.Handler("/docs", "/openapi.json", configure)
if err != nil {
log.Fatal(err)
}
func (*Builder) Title ¶
Title replaces the browser-tab title with plain text and returns the draft. The default is "API documentation". An empty title remains empty; HTML in the value is displayed as text rather than executed.
Example:
_, err := swagger.Handler("/docs", "/openapi.json", func(page *swagger.Builder) {
page.Title("Billing API")
})
if err != nil {
log.Fatal(err)
}
type BuilderFunc ¶
type BuilderFunc = func(*Builder)
BuilderFunc configures a fresh Builder synchronously during Handler. Callbacks run once in order; nil entries and callback panics propagate.
Example:
var configure swagger.BuilderFunc = func(page *swagger.Builder) {
page.Title("Billing API")
}
_, err := swagger.Handler("/docs", "/openapi.json", configure)
if err != nil {
log.Fatal(err)
}
Source Files