swagger

Documentation

Overview

Package swagger provides an HTTP handler to serve Swagger UI with embedded OpenAPI specs.

Index

• Constants
• func Download(opts DownloadOptions) (string, error)
• func GetLatestVersion() (string, error)
• type Config
• type DownloadOptions
• type GitHubRelease
• type Handler
  • func New(swaggerUIZip []byte, config Config) (*Handler, error)
  • func (h *Handler) Routes(mux *http.ServeMux)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) ServeResources(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) ServeSpec(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) ServeUI(w http.ResponseWriter, r *http.Request)
• type Resource

Constants

const (
	// GitHubReleasesAPI is the GitHub API endpoint for swagger-ui releases
	GitHubReleasesAPI = "https://api.github.com/repos/swagger-api/swagger-ui/releases/latest"
	// DownloadURLTemplate is the template for downloading swagger-ui releases
	DownloadURLTemplate = "https://github.com/swagger-api/swagger-ui/archive/refs/tags/%s.zip"
)

const DefaultCSS = `.swagger-ui .info .main > a, .swagger-ui .info .title > span {
    display: none;
}
`

DefaultCSS is the default custom CSS that hides the swagger branding.

const DefaultInitializer = `` /* 1533-byte string literal not displayed */

DefaultInitializer is the default swagger-initializer.js content that loads specs dynamically from the /openapi/resources endpoint.

const SimpleInitializer = `` /* 414-byte string literal not displayed */

SimpleInitializer is a simpler initializer for single-spec usage.

Functions

func Download

func Download(opts DownloadOptions) (string, error)

Download downloads and prepares Swagger UI for embedding.

func GetLatestVersion

func GetLatestVersion() (string, error)

GetLatestVersion fetches the latest Swagger UI version from GitHub.

Types

type Config

type Config struct {
	// BasePath is the URL path prefix where Swagger UI is served (e.g., "/swagger")
	BasePath string
	// SpecPath is the URL path to serve the OpenAPI spec (e.g., "/openapi/specs")
	SpecPath string
	// ResourcesPath is the URL path to serve the resources list (e.g., "/openapi/resources")
	ResourcesPath string
	// Specs is a map of spec name to spec content (YAML or JSON bytes)
	Specs map[string][]byte
	// DefaultSpec is the name of the default spec to serve when no query param is provided
	DefaultSpec string
}

Config holds the configuration for the Swagger UI handler.

type DownloadOptions

type DownloadOptions struct {
	// OutputDir is the directory where swagger-ui.zip will be saved
	OutputDir string
	// CustomCSS is optional custom CSS to inject
	CustomCSS string
	// CustomInitializer is optional custom JavaScript for swagger-initializer.js
	CustomInitializer string
	// Version is the specific version to download (empty for latest)
	Version string
}

DownloadOptions configures the Swagger UI download.

type GitHubRelease

type GitHubRelease struct {
	TagName string `json:"tag_name"`
	Name    string `json:"name"`
	HTMLURL string `json:"html_url"`
}

GitHubRelease represents the GitHub API response for a release.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler serves Swagger UI and OpenAPI specifications.

func New

func New(swaggerUIZip []byte, config Config) (*Handler, error)

New creates a new Swagger UI handler with the given configuration. swaggerUIZip should be the bytes of the swagger-ui.zip file.

func (*Handler) Routes

func (h *Handler) Routes(mux *http.ServeMux)

Routes registers the handler routes on the given mux.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

func (*Handler) ServeResources

func (h *Handler) ServeResources(w http.ResponseWriter, r *http.Request)

ServeResources serves the resources list. Use with chi: router.Get("/openapi/resources", h.ServeResources)

func (*Handler) ServeSpec

func (h *Handler) ServeSpec(w http.ResponseWriter, r *http.Request)

ServeSpec serves the OpenAPI spec. Use with chi: router.Get("/openapi/specs", h.ServeSpec)

func (*Handler) ServeUI

func (h *Handler) ServeUI(w http.ResponseWriter, r *http.Request)

ServeUI serves Swagger UI files. Use this when the router strips the base path (e.g., chi.Mount). The path should be relative to the mount point.

type Resource

type Resource struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

Resource represents a named OpenAPI spec URL for the Swagger UI dropdown.