Theming

Open-swag-go uses Scalar to render your API documentation UI. The UIConfig struct (the UI field on Config) controls colors, layout, dark mode, and custom CSS — either through a Scalar theme or your own styles.

UIConfig

Set the UI field on your Config to customize the documentation UI:

type UIConfig struct {
	Theme              string // Scalar theme name, passed to Scalar as-is (default "purple")
	DarkMode           bool   // Enable dark mode by default
	Layout             string // Scalar layout, passed as-is (default "modern")
	ShowSidebar        bool   // Show the navigation sidebar
	SidebarSearch      bool   // Deprecated: has no effect (v1.3.0+)
	TagGrouping        bool   // Deprecated: has no effect (v1.3.0+)
	CollapsibleSchemas bool   // Deprecated: has no effect (v1.3.0+)
	CustomCSS          string // Additional CSS to inject (trusted input only)
	ScalarVersion      string // Pin @scalar/api-reference; "" = ui.DefaultScalarVersion (v1.3.0+)
	SpecCORSOrigin     string // Access-Control-Allow-Origin on openapi.json: "" = "*", "-" = omitted (v1.3.0+)
}

Basic usage

cfg := openswag.Config{
	Info: openswag.Info{
		Title:   "My API",
		Version: "1.0.0",
	},
	UI: openswag.UIConfig{
		Theme:    "purple",
		DarkMode: true,
	},
}

Themes

open-swag-go has no theme list of its own. Theme is copied into the configuration object handed to Scalar and passed through unchanged as Scalar's theme option. Scalar 1.75 accepts: alternate, default, moon, purple, solarized, bluePlanet, saturn, kepler, mars, deepSpace, laserwave, none. An unknown name falls back to Scalar's default theme. When Theme is empty open-swag-go uses "purple"; Layout likewise defaults to "modern".

ui := openswag.UIConfig{Theme: "purple"} // or "bluePlanet", "kepler", "mars", ...

The list above is for the pinned Scalar release (see Pinning the Scalar Version); check Scalar's configuration reference if you pin another version. Earlier versions of this page listed blue, green and light as built-in themes. Those names came from the unused pkg/ui/themes.go file (removed in v1.3.0) and were never valid Scalar themes, so they silently rendered Scalar's default theme.

Dark Mode

Enable dark mode by default so the docs render with a dark background on first load:

cfg := openswag.Config{
	Info: openswag.Info{
		Title:   "My API",
		Version: "1.0.0",
	},
	UI: openswag.UIConfig{
		Theme:    "purple",
		DarkMode: true,
	},
}

When DarkMode is true, the Scalar UI loads in dark mode. Users can still toggle between light and dark in the rendered UI.

Custom CSS

Inject your own CSS to override colors, fonts, or layout details:

cfg := openswag.Config{
	Info: openswag.Info{
		Title:   "My API",
		Version: "1.0.0",
	},
	UI: openswag.UIConfig{
		Theme: "purple",
		CustomCSS: `
			:root {
				--scalar-color-1: #e91e63;
				--scalar-color-accent: #e91e63;
			}
			.scalar-app {
				font-family: "Inter", sans-serif;
			}
		`,
	},
}

CustomCSS is inserted verbatim into a <style> element, so it must come from your own configuration, never from user input. Everything else on the page is escaped: since v1.3.0 the HTML is rendered with html/template, so an Info.Title containing <, & or quotes is displayed as text.

Common CSS variables you can override:

Pinning the Scalar Version (v1.3.0+)

The docs page loads @scalar/api-reference from the jsDelivr CDN. The version is pinned, so a new upstream Scalar release does not change your docs UI by itself. The default is the ui.DefaultScalarVersion constant ("1.75.0" at the time of writing). Set ScalarVersion to choose another release:

ui := openswag.UIConfig{
	Theme:         "purple",
	ScalarVersion: "1.75.0", // exact @scalar/api-reference version
}

Before v1.3.0 the script URL had no version, so every visitor got the latest Scalar release.

Layout and Sidebar Options

ui := openswag.UIConfig{
	Theme:       "purple",
	Layout:      "modern",
	ShowSidebar: true,
}

SidebarSearch, TagGrouping and CollapsibleSchemas are deprecated and have no effect (v1.3.0+). They were never passed to Scalar, which always shows the sidebar search, groups operations by tag and renders model sections as collapsible. The fields are kept so existing configuration keeps compiling.

Full Example

A complete setup combining theme, dark mode, and custom CSS:

package main
 
import (
	"net/http"
 
	openswag "github.com/gopackx/open-swag-go"
	adapter "github.com/gopackx/open-swag-go/adapters/nethttp"
)
 
func main() {
	docs := openswag.New(openswag.Config{
		Info: openswag.Info{
			Title:       "Acme API",
			Version:     "2.0.0",
			Description: "The Acme Corp public API",
		},
		UI: openswag.UIConfig{
			Theme:    "purple",
			DarkMode: true,
			CustomCSS: `
				:root {
					--scalar-color-1: #0066ff;
					--scalar-color-accent: #0066ff;
				}
			`,
		},
	})
 
	mux := http.NewServeMux()
	adapter.Mount(mux, docs, "/docs")
 
	http.ListenAndServe(":8080", mux)
}