swgui

README

Swagger UI

Package swgui (Swagger UI) provides HTTP handler to serve Swagger UI. All assets are embedded in Go source code, so just build and run.

V5

Static assets for v5 are built from Swagger UI v5.17.14.

CDN-based v5cdn uses Swagger UI v5.17.14.

V4

Static assets for v4 are built from Swagger UI v4.19.1.

CDN-based v4cdn uses Swagger UI v4.18.3.

V3

Static assets for v3 are built from Swagger UI v3.52.5.

CDN-based v3cdn uses Swagger UI v3.52.4.

How to use

package main

import (
	"net/http"

	"github.com/swaggest/swgui/v5emb"
)

func main() {
	http.Handle("/api1/docs/", v5emb.New(
		"Petstore",
		"https://petstore3.swagger.io/api/v3/openapi.json",
		"/api1/docs/",
	))

	http.HandleFunc("/", func(writer http.ResponseWriter, request *http.Request) {
		_, _ = writer.Write([]byte("Hello World!"))
	})

	println("docs at http://localhost:8080/api1/docs/")
	_ = http.ListenAndServe("localhost:8080", http.DefaultServeMux)
}

If you use go1.16 or later, you can import natively embedded assets with "github.com/swaggest/swgui/v5emb", it may help to lower application memory usage.

Use CDN for assets

In order to reduce binary size you can import github.com/swaggest/swgui/v3cdn to use CDN hosted assets.

Also you can use swguicdn build tag to enable CDN mode for github.com/swaggest/swgui/v3 import.

Be aware that CDN mode may be considered inappropriate for security or networking reasons.

Documentation viewer CLI tool

Install swgui.

go install github.com/swaggest/swgui/cmd/swgui@latest

Or download binary from releases.

Linux AMD64

wget https://github.com/swaggest/swgui/releases/latest/download/linux_amd64.tar.gz && tar xf linux_amd64.tar.gz && rm linux_amd64.tar.gz
./swgui -version

Macos Intel

wget https://github.com/swaggest/swgui/releases/latest/download/darwin_amd64.tar.gz && tar xf darwin_amd64.tar.gz && rm darwin_amd64.tar.gz
codesign -s - ./swgui
./swgui -version

Macos Apple Silicon (M1, etc...)

wget https://github.com/swaggest/swgui/releases/latest/download/darwin_arm64.tar.gz && tar xf darwin_arm64.tar.gz && rm darwin_arm64.tar.gz
codesign -s - ./swgui
./swgui -version

Open spec file.

swgui my-openapi.yaml

Documentation

Overview

Package swgui provide a http FileSystem handler for swagger UI interface

How to generate asset files:

1. Install tools:

go get -u github.com/shurcooL/vfsgen

2. Generate file:

At root folder, run command:

go generate

Index

• type Config

Types

type Config

type Config struct {
	Title       string `json:"title"`          // Title of index file.
	SwaggerJSON string `json:"swaggerJsonUrl"` // URL to openapi.json/swagger.json document specification.
	BasePath    string `json:"basePath"`       // Base URL to docs.

	// InternalBasePath is used to override BasePath if external
	// url differs from internal one.
	InternalBasePath string `json:"-"`

	ShowTopBar         bool              `json:"showTopBar"`         // Show navigation top bar, hidden by default.
	HideCurl           bool              `json:"hideCurl"`           // Hide curl code snippet.
	JsonEditor         bool              `json:"jsonEditor"`         // Enable visual json editor support (experimental, can fail with complex schemas).
	PreAuthorizeApiKey map[string]string `json:"preAuthorizeApiKey"` // Map of security name to key value.

	// SettingsUI contains keys and plain javascript values of SwaggerUIBundle configuration.
	// Overrides default values.
	// See https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/ for available options.
	SettingsUI map[string]string `json:"-"`
}

Config is used for Swagger UI handler configuration.