Configuration

Configuration

app := rex.New(swagger.WithSwagger(swagger.NewConfig(
	swagger.WithServePath("/docs"),
	swagger.WithOpenAPIPath("/openapi.json"),
	swagger.WithTitle("Orders API"),
	swagger.WithDefaultTheme("dark"),
)))

swagger.WithSwagger(nil) takes the defaults.

⚠ A non-nil config is used verbatim

There is no field-by-field merge. A partial struct literal leaves everything else at its zero value:

// Wrong: ServePath "", OpenAPIPath "", Title "", DefaultTheme "".
swagger.WithSwagger(&swagger.Config{Title: "Orders API"})

// Right.
swagger.WithSwagger(swagger.NewConfig(swagger.WithTitle("Orders API")))

The merge used to exist and behaved as a trap: fields it forgot were silently ignored, fields it copied unconditionally were zeroed by a partial literal, and a deliberate zero could not be expressed at all.

Fields

type Config struct {
	ServePath    string            // "/apidoc"
	OpenAPIPath  string            // "/openapi.json"
	Title        string            // "API Documentation"
	DefaultTheme string            // "default"
	CustomThemes map[string][]byte // name → raw CSS
}

ServePath	where the UI is mounted. A redirect from ServePath to ServePath + "/" is registered automatically
OpenAPIPath	an absolute path or a full URL to the OpenAPI JSON, loaded by the browser
Title	the HTML <title>
DefaultTheme	"default", "dark", or a name registered with WithCustomTheme
CustomThemes	served at <ServePath>/assets/themes/<name>.css

Options

WithServePath(p)	mount point
WithOpenAPIPath(p)	path or URL to the document
WithTitle(s)	page title
WithDefaultTheme(name)	theme on first load
WithCustomTheme(name, css)	register a theme; repeat calls with one name overwrite

OpenAPIPath is resolved by the browser

It is fetched by the page, not by the server — so it must be reachable from the browser, not merely from the process.

// Same origin — the usual case.
swagger.WithOpenAPIPath("/openapi.json")

// A document served elsewhere. The other origin must allow the request.
swagger.WithOpenAPIPath("https://api.example.com/openapi.json")

A cross-origin document needs CORS on that origin. If the document is served by the same application on another router, rextension-cors has to allow the UI's origin.

Base paths

If the router has a BaseURL, that prefix is added by the router — write ServePath and OpenAPIPath relative to the router, exactly as you would a route pattern:

app.CreateRouter("api", rex.RouterConfig{Addr: ":8080", BaseURL: "/api/v1"})
// UI at /api/v1/apidoc/, document at /api/v1/openapi.json

Environment-conditional registration

The UI publishes your whole API surface and invites people to call it. A common shape:

opts := []rex.Option{
	rex.WithConfig(cfg),
	openapi.WithOpenAPI(apiCfg),
}
if env != "production" {
	opts = append(opts, swagger.WithSwagger(swagger.NewConfig(
		swagger.WithTitle("Orders API ("+env+")"),
	)))
}
app := rex.New(opts...)

Putting the environment in the title is a small thing that prevents a surprisingly common mistake — testing against production because two tabs look identical.

Version

swagger.SwaggerUIVersion // "5.18.2"

Bundled at build time. Upgrading Swagger UI means upgrading this module.