openapiui

README

OpenAPI 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
• ⚡ 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/openapi-ui

Quick Start

package main

import (
	"log"
	"net/http"

	openapiui "github.com/oaswrap/openapi-ui"
	"github.com/oaswrap/openapi-ui/config"
)

func main() {
	mux := http.NewServeMux()

	// Swagger UI
	swaggerHandler := openapiui.NewHandler(openapiui.SwaggerUI(config.Swagger{
		Title:       "Petstore API",
		BasePath:    "/docs/swagger",
		OpenAPIYAML: "/docs/openapi.yaml",
	}))

	// Stoplight Elements
	elementsHandler := openapiui.NewHandler(openapiui.StoplightElements(config.Elements{
		Title:       "Petstore API",
		BasePath:    "/docs/elements",
		OpenAPIYAML: "/docs/openapi.yaml",
	}))

	// Redoc
	redocHandler := openapiui.NewHandler(openapiui.Redoc(config.Redoc{
		Title:       "Petstore API",
		BasePath:    "/docs/redoc",
		OpenAPIYAML: "/docs/openapi.yaml",
	}))

	// Register handlers
	mux.Handle("GET /docs/swagger", swaggerHandler)
	mux.Handle("GET /docs/elements", elementsHandler)
	mux.Handle("GET /docs/redoc", redocHandler)
	mux.HandleFunc("GET /docs/openapi.yaml", docsFileHandler)

	log.Printf("Swagger UI available at http://localhost:3000/docs/swagger")
	log.Printf("Stoplight Elements available at http://localhost:3000/docs/elements")
	log.Printf("Redoc available at http://localhost:3000/docs/redoc")
	log.Printf("OpenAPI YAML available at http://localhost:3000/docs/openapi.yaml")

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

func docsFileHandler(w http.ResponseWriter, r *http.Request) {
	http.ServeFile(w, r, "openapi.yaml")
}

UI Options

Swagger UI

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

swaggerHandler := openapiui.NewHandler(openapiui.SwaggerUI(config.Swagger{
	Title:       "My API",
	BasePath:    "/docs/swagger",
	OpenAPIYAML: "/docs/openapi.yaml",
}))

Redoc

A clean, responsive documentation interface optimized for readability.

redocHandler := openapiui.NewHandler(openapiui.Redoc(config.Redoc{
	Title:       "My API",
	BasePath:    "/docs/redoc",
	OpenAPIYAML: "/docs/openapi.yaml",
}))

Stoplight Elements

Modern, customizable API documentation with excellent developer experience.

elementsHandler := openapiui.NewHandler(openapiui.StoplightElements(config.Elements{
	Title:       "My API",
	BasePath:    "/docs/elements",
	OpenAPIYAML: "/docs/openapi.yaml",
}))

Configuration Options

Common Configuration Fields

All UI configurations share these common fields:

• Title: The title displayed in the documentation UI
• BasePath: The base path where the UI will be served
• OpenAPIYAML: The URL to your OpenAPI specification file (YAML or JSON)

Swagger UI Configuration

config.Swagger{
    Title:       "My API",                    // Title of the documentation page
    OpenAPIYAML: "/docs/openapi.yaml",        // URL to OpenAPI specification
    BasePath:    "/docs",                     // Base URL path for the docs
    
    ShowTopBar:         true,                 // Show navigation top bar (hidden by default)
    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",
    },
}

Advanced Swagger Configuration:

• ShowTopBar: Shows the Swagger UI navigation bar at the top
• HideCurl: Removes curl command examples from the interface
• JsonEditor: Enables experimental visual JSON editor for request bodies
• PreAuthorizeApiKey: Pre-fills API keys for authentication (security name → key value)
• SettingsUI: Direct SwaggerUI configuration overrides (see SwaggerUI docs)

Stoplight Elements Configuration

config.Elements{
    Title:       "My API",                    // Title of the documentation page
    OpenAPIYAML: "/docs/openapi.yaml",        // URL to OpenAPI specification
    BasePath:    "/docs",                     // Base URL path for the docs

    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
}

Stoplight Elements Options:

• HideExport: Removes the export button from the overview section
• HideSchemas: Hides schema definitions from the sidebar Table of Contents
• HideTryIt: Disables the interactive "Try it" API testing feature
• Layout: Choose between "sidebar" (fixed sidebar) or "responsive" layout
• Logo: URL to a square logo image displayed next to the title
• Router: Router type for navigation (e.g., "hash", "memory")

Redoc Configuration

config.Redoc{
    Title:       "My API",                    // Title of the documentation page
    OpenAPIYAML: "/docs/openapi.yaml",        // URL to OpenAPI specification
    BasePath:    "/docs",                     // Base URL path for the docs

    HideDownload: false,                      // Hide download button for OpenAPI spec
}

Redoc Options:

• HideDownload: Removes the download button for saving the OpenAPI specification file

Configuration Examples

HTTP

import "net/http"

mux := http.NewServeMux()
mux.Handle("GET /docs", swaggerHandler)

Gin

import "github.com/gin-gonic/gin"

r := gin.Default()
r.GET("/docs", gin.WrapH(swaggerHandler))

Echo

import "github.com/labstack/echo/v4"

e := echo.New()
e.GET("/docs", echo.WrapHandler(swaggerHandler))

Gorilla Mux

import "github.com/gorilla/mux"

r := mux.NewRouter()
r.Handle("/docs", swaggerHandler).Methods("GET")

Fiber

import (
    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/adaptor"
)

app := fiber.New()
app.Get("/docs", adaptor.HTTPHandler(swaggerHandler))

OpenAPI Specification

Ensure your OpenAPI specification file is accessible via HTTP. You can serve it as a static file or generate it dynamically:

Static File

mux.HandleFunc("GET /docs/openapi.yaml", func(w http.ResponseWriter, r *http.Request) {
	http.ServeFile(w, r, "path/to/your/openapi.yaml")
})

Dynamic Generation

mux.HandleFunc("GET /docs/openapi.yaml", func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/yaml")
	// Generate or load your OpenAPI spec
	spec := generateOpenAPISpec()
	w.Write([]byte(spec))
})

Examples

Check out the examples directory for more usage patterns:

• Basic HTTP server setup
• Integration with popular Go frameworks
• Custom configuration options
• Dynamic OpenAPI spec generation

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

Documentation

Index

• func NewHandler(opt Option) http.Handler
• type Option
  • func Redoc(cfg config.Redoc) Option
  • func StoplightElements(cfg config.Elements) Option
  • func SwaggerUI(cfg config.Swagger) Option

Functions

func NewHandler

func NewHandler(opt Option) http.Handler

NewHandler creates a new HTTP handler for the OpenAPI UI.

It applies the provided options to configure the OpenAPI UI.

Example:

import (
    "net/http"

    openapiui "github.com/oaswrap/openapi-ui"
    "github.com/oaswrap/openapi-ui/config"
)

func main() {
    handler := openapiui.NewHandler(
        openapiui.StoplightElement(config.Element{
            Title:       "My API",
            OpenAPIYAML: "/path/to/openapi.yaml",
            BasePath:    "/api",
        }),
    )
    http.Handle("/docs", handler)
    http.ListenAndServe(":8080", nil)
}

Types

type Option

type Option func(*config.OpenAPIUI)

Option is a function that configures the OpenAPI UI.

func Redoc

func Redoc(cfg config.Redoc) Option

Redoc sets up the Redoc configuration.

func StoplightElements

func StoplightElements(cfg config.Elements) Option

StoplightElements sets up the Stoplight Elements configuration.

func SwaggerUI

func SwaggerUI(cfg config.Swagger) Option

SwaggerUI sets up the Swagger UI configuration.