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 predefined themes or your own styles.

UIConfig

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

ui_config.go

type UIConfig struct {
	Theme              string // Predefined theme: "purple", "blue", "green", "light"
	DarkMode           bool   // Enable dark mode by default
	Layout             string // Layout style, e.g. "modern"
	ShowSidebar        bool   // Show the navigation sidebar
	SidebarSearch      bool   // Enable the sidebar search box
	TagGrouping        bool   // Group endpoints by tag
	CollapsibleSchemas bool   // Render schemas as collapsible sections
	CustomCSS          string // Additional CSS to inject
}

Basic usage

theming_basic.go

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

Predefined Themes

Open-swag-go ships with four built-in themes:

Theme	Description
`purple`	Default theme with purple accent colors
`blue`	Blue accent, clean and professional
`green`	Green accent, ideal for health/nature APIs
`light`	Minimal light theme with neutral tones

theme_selection.go

ui := openswag.UIConfig{Theme: "purple"} // or "blue", "green", "light"

Dark Mode

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

dark_mode.go

cfg := openswag.Config{
	Info: openswag.Info{
		Title:   "My API",
		Version: "1.0.0",
	},
	UI: openswag.UIConfig{
		Theme:    "blue",
		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:

custom_css.go

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;
			}
		`,
	},
}

Common CSS variables you can override:

Variable	Controls
`--scalar-color-1`	Primary accent color
`--scalar-color-accent`	Links and interactive elements
`--scalar-color-background-1`	Main background
`--scalar-color-background-2`	Sidebar / secondary background

layout_options.go

ui := openswag.UIConfig{
	Theme:              "blue",
	Layout:             "modern",
	ShowSidebar:        true,
	SidebarSearch:      true,
	TagGrouping:        true,
	CollapsibleSchemas: true,
}

Full Example

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

full_theming.go

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:    "blue",
			DarkMode: true,
			CustomCSS: `
				:root {
					--scalar-color-1: #0066ff;
					--scalar-color-accent: #0066ff;
				}
			`,
		},
	})
 
	mux := http.NewServeMux()
	adapter.Mount(mux, docs, "/docs")
 
	http.ListenAndServe(":8080", mux)
}