specui

Spec UI

A Go library that provides multiple OpenAPI documentation UIs including Swagger UI, Redoc, and Stoplight Elements. Easily serve beautiful, interactive API documentation for your OpenAPI specifications.

Features

• 🚀 Multiple UI Options: Support for Swagger UI, Redoc, and Stoplight Elements
• 📱 Responsive Design: All UIs are mobile-friendly and responsive
• ⚡ 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("Petstore 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

Modern, customizable API documentation with excellent developer experience.

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

Swagger UI

The classic, feature-rich OpenAPI documentation interface with interactive API exploration.

handler := specui.NewHandler(
	specui.WithTitle("My API"),
	specui.WithDocsPath("/docs"),
	specui.WithSpecPath("/docs/openapi.yaml"),
	specui.WithSpecFile("openapi.yaml"),
	specui.WithSwaggerUI(config.SwaggerUI{
		ShowTopBar:         true,
		HideCurl:           false,
		JsonEditor:         true,
		PreAuthorizeApiKey: map[string]string{
			"api_key": "your-api-key-here",
		},
		SettingsUI: map[string]string{
			"deepLinking": "true",
			"filter":      "true",
		},
	}),
)

Redoc

A clean, responsive documentation interface optimized for readability.

handler := specui.NewHandler(
	specui.WithTitle("My API"),
	specui.WithDocsPath("/docs"),
	specui.WithSpecPath("/docs/openapi.yaml"),
	specui.WithSpecFile("openapi.yaml"),
	specui.WithRedoc(config.Redoc{
		HideDownload: false,
	}),
)

Handler Methods

The handler provides convenient methods for integration:

• handler.Docs() - Return 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 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

specui.WithTitle("My API")                   				// Set documentation title
specui.WithDocsPath("/docs")								// Set documentation URL path
specui.WithSpecPath("/docs/openapi.yaml")     				// Set OpenAPI spec URL path
specui.WithSpecFile("openapi.yaml")            				// Specify OpenAPI specification file path
specui.WithSpecEmbedFS("openapi.yaml", embedFS)     	 	// Use embedded filesystem for spec
specui.WithSpecIOFS("openapi.yaml", os.DirFS("testdata")) 	// Use OS filesystem for spec

UI Selection with Configuration

Stoplight Elements Configuration

specui.WithStoplightElements(config.StoplightElements{
	HideExport:  false,                           // Hide the "Export" button
	HideSchemas: false,                           // Hide schemas in Table of Contents
	HideTryIt:   false,                           // Hide "Try it" interactive feature
	Layout:      "sidebar",                       // Layout: "sidebar" or "responsive"
	Logo:        "/assets/logo.png",              // URL to logo image
	Router:      "hash",                          // Router type: "hash", "memory"
})

// Or use with defaults (Layout: "sidebar", Router: "hash")
specui.WithStoplightElements()

Swagger UI Configuration

specui.WithSwaggerUI(config.SwaggerUI{
	ShowTopBar:         true,                     // Show navigation top bar
	HideCurl:           false,                    // Hide curl code snippets
	JsonEditor:         true,                     // Enable visual JSON editor (experimental)
	PreAuthorizeApiKey: map[string]string{        // Pre-authorize API keys
		"api_key": "your-api-key-here",
		"bearer":  "your-bearer-token",
	},
	SettingsUI: map[string]string{                // Advanced SwaggerUI configuration
		"deepLinking":            "true",
		"displayRequestDuration": "true",
		"filter":                 "true",
		"showExtensions":         "true",
	},
})

// Or use with defaults
specui.WithSwaggerUI()

Redoc Configuration

specui.WithRedoc(config.Redoc{
	HideDownload: false,  		// Hide download button for OpenAPI spec
	DisableSearch:    false, 	// Disable search functionality
	HideSchemaTitles: false,	// Hide schema titles
})

// Or use with defaults
specui.WithRedoc()

Configuration Examples

Complete Example with All Options

handler := specui.NewHandler(
	// Core configuration
	specui.WithTitle("Pet Store API"),
	specui.WithDocsPath("/documentation"),
	specui.WithSpecPath("/documentation/openapi.yaml"),
	specui.WithSpecFile("specs/petstore.yaml"),
	
	// Swagger UI with full configuration
	specui.WithSwaggerUI(config.SwaggerUI{
		ShowTopBar:  true,
		JsonEditor:  true,
		PreAuthorizeApiKey: map[string]string{
			"api_key": "demo-key",
			"bearer":  "demo-token",
		},
		SettingsUI: map[string]string{
			"deepLinking":            "true",
			"displayRequestDuration": "true",
			"filter":                 "true",
		},
	}),
)

Minimal Configuration

// Uses sensible defaults
handler := specui.NewHandler(
	specui.WithSpecFile("openapi.yaml"),
	specui.WithSwaggerUI(),
)
// Default paths: /docs and /docs/openapi.yaml

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.

Support

• 📖 Documentation: Check the examples and configuration options above
• 🐛 Issues: Report bugs or request features via GitHub Issues
• 💬 Discussions: Join the community discussions for questions and ideas

Made with ❤️ for the Go community