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

Installation

go get github.com/oaswrap/spec-ui

Quick Start

package main

import (
	"log"
	"net/http"

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

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

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

	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

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

handler := specui.NewHandler(
	specui.WithTitle("My API"),
	specui.WithSpecFile("openapi.yaml"),
	specui.WithStoplightElements(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

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

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

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

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

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

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

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

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)

Basic Usage

The API uses a builder pattern with functional options for flexible configuration:

// 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
	specui.WithStoplightElements(config.StoplightElements{  // Choose UI with config
		HideExport: false,
		HideTryIt:  false,
	}),
)

// Minimal setup (uses sensible defaults)
handler := specui.NewHandler(
	specui.WithSpecFile("openapi.yaml"),
	specui.WithSwaggerUI(), // 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:

Core Options

UI Selection with Configuration

Stoplight Elements Configuration

Usage:

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

Swagger UI Configuration

Usage:

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

ReDoc Configuration

Usage:

specui.WithReDoc(config.ReDoc{
	DisableSearch:       true,
	HideDownloadButtons: true,
	HideSchemaTitles:    true,
})

Scalar Configuration

Usage:

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

RapiDoc Configuration

Usage:

specui.WithRapiDoc(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 feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

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

Made with ❤️ for the Go community