specui

Spec UI

A Go library that provides multiple OpenAPI documentation UIs. Serve beautiful, interactive API documentation for your OpenAPI specifications.

Features

• 🚀 Multiple UI Options: Support for Swagger UI, Stoplight Elements, ReDoc, Scalar and RapiDoc
• ⚡ Easy Integration: Simple HTTP handler integration with Go's standard library
• 🎨 Customizable: Configure titles, base paths, and OpenAPI spec locations
• 🔧 Flexible: Works with any Go HTTP router or framework
• 📦 Optional Embedded UI Assets: Enable local embedded assets for self-contained binaries in air-gapped environments

Installation

go get github.com/oaswrap/spec-ui

Quick Start

any

package main

import (
	"log"
	"net/http"

	"github.com/go-chi/chi/v5"
	specui "github.com/oaswrap/spec-ui"
	"github.com/oaswrap/spec-ui/stoplight"
)

func main() {
	r := chi.NewRouter()

	handler := specui.NewHandler(
		specui.WithTitle("Pet Store API"),
		specui.WithDocsPath("/docs"),
		specui.WithSpecPath("/docs/openapi.yaml"),
		specui.WithSpecFile("openapi.yaml"),
		stoplight.WithUI(),
	)

	r.Get(handler.DocsPath(), handler.DocsFunc())
	r.Get(handler.SpecPath(), handler.SpecFunc())

	log.Printf("OpenAPI Documentation available at http://localhost:3000/docs")
	log.Printf("OpenAPI YAML available at http://localhost:3000/docs/openapi.yaml")

	http.ListenAndServe(":3000", r)
}

UI Options

Each UI provider is accessed through its own package. Import the provider package and use its WithUI() option to enable it.

Stoplight Elements

Beautiful Three-Column Design - Modern API documentation with a "Stripe-esque" three-column layout, powered by OpenAPI and Markdown for an elegant developer experience.
View Demo

import (
	"github.com/oaswrap/spec-ui/config"
	"github.com/oaswrap/spec-ui/stoplight"
)

handler := specui.NewHandler(
	specui.WithTitle("My API"),
	specui.WithSpecFile("openapi.yaml"),
	stoplight.WithUI(config.StoplightElements{
		HideExport:  false,
		HideSchemas: false,
		HideTryIt:   false,
		Layout:      "sidebar",
		Logo:        "/assets/logo.png",
		Router:      "hash",
	}),
)

Swagger UI

Interactive API Explorer - Your interactive coding buddy for AI-driven API testing workflows, widely used by developers with extensive framework integrations.
View Demo

import "github.com/oaswrap/spec-ui/swaggerui"

handler := specui.NewHandler(
	specui.WithTitle("My API"),
	specui.WithSpecFile("openapi.yaml"),
	swaggerui.WithUI(),
)

ReDoc

Modern Three-Column Layout - Similar to Swagger UI but renders documentation in a modern three-column format, perfect for polished executive summaries and presenting API schemas.
View Demo

import "github.com/oaswrap/spec-ui/redoc"

handler := specui.NewHandler(
	specui.WithTitle("My API"),
	specui.WithSpecFile("openapi.yaml"),
	redoc.WithUI(),
)

Scalar

Feature-Rich Modern Interface - Provides the most feature-rich interface compared to Swagger UI and ReDoc, with built-in themes, search function, and code examples.
View Demo

import "github.com/oaswrap/spec-ui/scalar"

handler := specui.NewHandler(
	specui.WithTitle("My API"),
	specui.WithSpecFile("openapi.yaml"),
	scalar.WithUI(),
)

RapiDoc

Flexible Rendering Styles - Web component-based viewer with multiple themes, styling options, and distinctive tabular/tree model representations perfect for large schemas.
View Demo

import "github.com/oaswrap/spec-ui/rapidoc"

handler := specui.NewHandler(
	specui.WithTitle("My API"),
	specui.WithSpecFile("openapi.yaml"),
	rapidoc.WithUI(),
)

Handler Methods

The handler provides convenient methods for integration:

• handler.Docs() - Returns HTTP handler for the documentation UI
• handler.DocsFunc() - Returns the HTTP handler function for the documentation UI
• handler.DocsPath() - Returns the documentation path (e.g., /docs)
• handler.Spec() - Returns HTTP handler for the OpenAPI specification
• handler.SpecFunc() - Returns the HTTP handler function for serving the OpenAPI specification
• handler.SpecPath() - Returns the OpenAPI spec path (e.g., /docs/openapi.yaml)
• handler.AssetsEnabled() - Returns true when UI assets are served from embedded files
• handler.AssetsPath() - Returns the assets URL prefix (default: /docs/_assets)
• handler.Assets() - Returns the embedded assets handler (or nil in CDN mode)

Architecture Overview

The library uses a provider-based architecture for maximum flexibility and code efficiency:

Provider Packages: Each UI provider is accessed through its own package:

• github.com/oaswrap/spec-ui/swaggerui - Swagger UI with CDN assets
• github.com/oaswrap/spec-ui/stoplight - Stoplight Elements with CDN assets
• github.com/oaswrap/spec-ui/redoc - ReDoc with CDN assets
• github.com/oaswrap/spec-ui/scalar - Scalar with CDN assets
• github.com/oaswrap/spec-ui/rapidoc - RapiDoc with CDN assets

Embedded Packages: Each provider also has an *emb variant for self-contained deployments:

• github.com/oaswrap/spec-ui/swaggeruiemb - Swagger UI with embedded assets
• github.com/oaswrap/spec-ui/stoplightemb - Stoplight Elements with embedded assets
• github.com/oaswrap/spec-ui/redocemb - ReDoc with embedded assets
• github.com/oaswrap/spec-ui/scalaremb - Scalar with embedded assets
• github.com/oaswrap/spec-ui/rapidocemb - RapiDoc with embedded assets

How It Works:

1. Each provider package exports a WithUI(cfg...) option
2. This option configures the DocsHandlerFactory that creates the handler for the selected UI
3. When handler.Docs() is called, it uses the factory to instantiate the provider's handler
4. Only the selected provider's code is linked into the binary, enabling Go's linker to tree-shake unused providers

This architecture provides:

• Small binaries: Only selected provider code is included
• Easy switching: Change provider by switching the import package
• Flexibility: Supports both CDN and embedded asset modes
• Extensibility: New providers can be added without modifying the core package

Embedded Assets (Optional)

By default, UI CSS/JS assets are loaded from CDN.

If you need offline or air-gapped usage, use the provider-specific *emb packages instead.

No extra download step is required for library users; embedded assets are already included in this module.

Each provider has a corresponding *emb package that serves embedded assets:

Usage with Embedded Assets:

import (
	specui "github.com/oaswrap/spec-ui"
	"github.com/oaswrap/spec-ui/swaggeruiemb"  // Use embed package
)

handler := specui.NewHandler(
	specui.WithSpecFile("openapi.yaml"),
	swaggeruiemb.WithUI(),  // Enables embedded assets automatically
)

r.Get(handler.DocsPath(), handler.DocsFunc())
r.Get(handler.SpecPath(), handler.SpecFunc())

if handler.AssetsEnabled() {
	r.Get(handler.AssetsPath()+"/*", handler.Assets().ServeHTTP)
}

Benefits:

• Tree-shaking: Only the selected provider's code is linked into the binary
• CDN mode (default): Lightweight binaries, assets loaded from CDN
• Embed mode: Self-contained binaries for offline or air-gapped environments

Notes:

• Use provider packages (swaggerui, stoplight, scalar, redoc, rapidoc) for CDN mode
• Use provider *emb packages (swaggeruiemb, stoplightemb, scalaremb, redocemb, rapidocemb) for embedded assets
• The handler.AssetsEnabled() method returns true only when using an *emb package

Basic Usage

The API uses a builder pattern with functional options for flexible configuration. Each UI provider is selected via its own package:

import (
	specui "github.com/oaswrap/spec-ui"
	"github.com/oaswrap/spec-ui/swaggerui"  // or any other provider
	"github.com/oaswrap/spec-ui/config"
)

// Complete example with all available options
handler := specui.NewHandler(
	specui.WithTitle("My API"),                    // Set documentation title
	specui.WithDocsPath("/docs"),                  // Set docs URL path
	specui.WithSpecPath("/docs/openapi.yaml"),     // Set spec URL path
	specui.WithSpecFile("openapi.yaml"),           // Set the spec file location
	swaggerui.WithUI(config.SwaggerUI{             // Choose UI provider with config
		HideCurl: false,
		Layout:   "StandaloneLayout",
	}),
)

// Minimal setup (uses sensible defaults)
handler := specui.NewHandler(
	specui.WithSpecFile("openapi.yaml"),
	swaggerui.WithUI(), // No config needed, uses defaults
)

// Register with any HTTP router
r.Get(handler.DocsPath(), handler.DocsFunc())   // Documentation UI
r.Get(handler.SpecPath(), handler.SpecFunc())   // OpenAPI spec file

Configuration Options

The library uses functional options for flexible configuration through provider packages.

Core Options (Main Package)

UI Provider Selection

Each UI provider package exports a WithUI(config...) option:

Provider Configuration

Stoplight Elements Configuration

Usage:

import (
	"github.com/oaswrap/spec-ui/config"
	"github.com/oaswrap/spec-ui/stoplight"
)

stoplight.WithUI(config.StoplightElements{
	HideExport:		false,
	HideSchemas:	false,
	HideTryIt:		false,
	HideTryItPanel:	false,
	Layout:			"sidebar",
	Logo:			"/assets/logo.png",
	Router:			"hash",
})

Swagger UI Configuration

Usage:

import (
	"github.com/oaswrap/spec-ui/config"
	"github.com/oaswrap/spec-ui/swaggerui"
)

swaggerui.WithUI(config.SwaggerUI{
	HideCurl:   				false,
	JsonEditor: 				true,
	Layout:     				"StandaloneLayout",
	DefaultModelsExpandDepth:	1,
})

ReDoc Configuration

Usage:

import (
	"github.com/oaswrap/spec-ui/config"
	"github.com/oaswrap/spec-ui/redoc"
)

redoc.WithUI(config.ReDoc{
	HideSearch:          true,
	HideDownloadButtons: true,
	HideSchemaTitles:    true,
})

Scalar Configuration

Usage:

import (
	"github.com/oaswrap/spec-ui/config"
	"github.com/oaswrap/spec-ui/scalar"
)

scalar.WithUI(config.Scalar{
	ProxyURL:                "https://proxy.scalar.com",
	HideSidebar:             false,
	HideModels:              false,
	DocumentDownloadType:    "both",
	HideTestRequestButton:   false,
	HideSearch:              false,
	HideDeveloperTools:      false,
	DarkMode:                true,
	Layout:                  "modern",
	Theme:                   "moon",
})

RapiDoc Configuration

Usage:

import (
	"github.com/oaswrap/spec-ui/config"
	"github.com/oaswrap/spec-ui/rapidoc"
)

rapidoc.WithUI(config.RapiDoc{
	Theme:               "light",
	Layout:              "row",
	RenderStyle:         "read",
	SchemaStyle:         "table",
	BgColor:             "#fff",
	TextColor:           "#444",
	HeaderColor:         "#444444",
	PrimaryColor:        "#FF791A",
	HideInfo:            false,
	HideHeader:          false,
	HideSearch:          false,
	HideAdvancedSearch:  false,
	HideTryIt:           false,
	Logo:                "/assets/logo.png",
})

Examples

Check out the examples directory for more examples.

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for setup, checks, and pull request guidelines.

License

This project is licensed under the MIT License—see the LICENSE file for details.

Made with ❤️ for the Go community