Theming

Open-swag-go uses Scalar to render your API documentation UI. The ScalarConfig struct gives you control over colors, layout, and dark mode — either through predefined themes or custom CSS.

ScalarConfig

Pass a ScalarConfig to your Config to customize the documentation UI:

scalar_config.go

type ScalarConfig struct {
	Theme       string // Predefined theme name
	DarkMode    bool   // Enable dark mode by default
	CustomCSS   string // Additional CSS to inject
	HideModels  bool   // Hide the models/schemas section
	HideSidebar bool   // Hide the sidebar navigation
}

Basic usage

theming_basic.go

docs := openswag.Config{
	Title:   "My API",
	Version: "1.0.0",
	UIConfig: openswag.UIConfig{
		Scalar: &openswag.ScalarConfig{
			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

// Purple (default)
scalar := openswag.ScalarConfig{Theme: "purple"}
 
// Blue
scalar = openswag.ScalarConfig{Theme: "blue"}
 
// Green
scalar = openswag.ScalarConfig{Theme: "green"}
 
// Light
scalar = openswag.ScalarConfig{Theme: "light"}

Dark Mode

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

dark_mode.go

docs := openswag.Config{
	Title:   "My API",
	Version: "1.0.0",
	UIConfig: openswag.UIConfig{
		Scalar: &openswag.ScalarConfig{
			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

docs := openswag.Config{
	Title:   "My API",
	Version: "1.0.0",
	UIConfig: openswag.UIConfig{
		Scalar: &openswag.ScalarConfig{
			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

Hiding UI Sections

You can hide parts of the UI to simplify the docs:

hide_sections.go

scalar := openswag.ScalarConfig{
	Theme:       "blue",
	HideModels:  true, // Remove the schemas section
	HideSidebar: true, // Remove sidebar navigation
}

Full Example

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

full_theming.go

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

On this page