Skip to content

feat(doc): customize the docs page tab title and icon - #77

Merged
josuegiron merged 1 commit into
masterfrom
feat/doc-tab-icon-title
Nov 21, 2026
Merged

josuegiron merged 1 commit into
masterfrom
feat/doc-tab-icon-title

Conversation

@josuegiron

Copy link
Copy Markdown
Member

Fixes #73 (API-17).

Scope

  • Includes: doc.SwaggerUIHandler(openAPIURL string, opts ...SwaggerUIOption), doc.WithTitle, doc.WithFavicon, a generic default favicon, tests, Examples, README and docs/openapi.md.
  • Leaves out: the Exporter interface and the built-in swagger exporter (unchanged, changing them would be breaking).
  • Standalone PR (1 of 1); nothing stacked on top.

Changes

  • SwaggerUIOption func(*swaggerUIConfig) (unexported config). Options are applied once when the handler is built; nil options are skipped.
  • WithTitle(title): page <title>; default API Docs; empty keeps the default.
  • WithFavicon(href): URL or data: URI (PNG, SVG, ICO), written as <link rel="icon">; empty keeps the default.
  • Both values go through html.EscapeString. Not html/template: its URL filter rewrites data: URIs to #ZgotmplZ. The JSON-encoded OpenAPI URL and the swagger-ui-dist 5.34.1 SRI pins are unchanged.
  • Default icon (owner update): the page now always has a <link rel="icon"> with an original, single-color (#808080) { } SVG, URL-encoded as a data:image/svg+xml,... URI (no external fetch, no third-party logo). WithFavicon replaces it.
  • Exporter registry: services that serve docs via doc.ExporterByName register their own exporter that calls SwaggerUIHandler with options (ExampleRegisterExporter, docs/openapi.md). Using a distinct name keeps the built-in swagger untouched.

Release notes (v1.1.0)

  • New: doc.SwaggerUIHandler accepts options: doc.WithTitle("Orders API"), doc.WithFavicon("/static/icon.png") (URL or data: URI). Values are HTML-escaped. Existing calls compile unchanged.
  • Changed: the Swagger UI page now ships a generic default favicon (inline { } SVG), so the browser tab no longer shows the generic globe. The default page differs from v1.0.0 only by that one <link rel="icon"> line; the title is still API Docs.
  • Tip: percent-encode or base64-encode SVG data: URIs passed to WithFavicon (a raw # starts a URL fragment).

Verification

Test-first: a golden file (doc/testdata/swagger-ui-default.html, the v1.0.0 page plus the icon line) and table-driven tests for title/favicon values, escaping/injection, empty values, nil option and the default icon's encoding (decodes to well-formed SVG).

  • gofmt -l .: no output
  • go vet ./...: ok
  • go test -race ./...: ok (all packages, ExampleSwaggerUIHandler, ExampleRegisterExporter)
  • govulncheck ./...: no vulnerabilities found

🤖 Generated with Claude Code

SwaggerUIHandler takes variadic SwaggerUIOption values: WithTitle sets
the page title and WithFavicon sets the tab icon (URL or data: URI).
Both are HTML-escaped; empty values keep the defaults. The page now
ships a generic inline "{ }" SVG icon by default, so the tab never shows
the browser globe. The Exporter interface is unchanged; services pass
options through the registry by registering their own exporter.

Fixes #73

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@josuegiron
josuegiron merged commit 22ab990 into master Nov 21, 2026
2 checks passed
@josuegiron
josuegiron deleted the feat/doc-tab-icon-title branch November 21, 2026 19:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

API-17: Customize the docs page tab icon and title

1 participant