swagserver

README

swagserver

Swagserver is a simple project designed to serve your swagger ui using a valid specification file. It can be added as a middleware or registered as a dedicated http handler. It was intially built to be using with go swagger generated servers - but should be pluggable with with most routing frameworks.

Swagger UI Versions

Curious what swagger ui version we are on?

The corresponding swagger ui version is included in the swagserver release notes.

Setup and usage

go get github.com/syllabix/swagserver@latest

As a handler with a go swagger generated API

func main() {

	// initialize a new swag server handler
	swagger := swagserver.NewHandler(
		option.SwaggerSpecURL("/swagger.json"),
		option.Theme(theme.Muted),
		option.Path("/docs/"),
	)

	// initialize your go swagger server
	spec, err := loads.Analyzed(rest.FlatSwaggerJSON, "")
	if err != nil {
		log.Fatal("nope... not this time", err)
	}
	api := operation.NewAwesomeAPI(spec)
	api.JSONConsumer = runtime.JSONConsumer()
	api.JSONProducer = runtime.JSONProducer()


	mux := http.NewServeMux()

	// register swagger as a hendler
	mux.Handle("/docs/", swagger)

	// otherwise serve the api
	mux.Handle("/", api.Serve(nil))

	server := http.Server{
		Addr:    ":9091",
		Handler: mux,
	}

	fmt.Println("starting server")
	server.ListenAndServe()
}

As a middleware

func setupGlobalMiddleware(handler http.Handler) http.Handler {
	swagserve := swagserver.New(
		option.Path("/internal/apidocs"),
		option.SwaggerSpecURL("/swagger.json"),
		option.Theme(theme.Material),
	)
	return swagserve(handler)
}

Options

Path - the the url path swagger ui should be served at

Disable - swagger ui will not be rendered

SwaggerSpecURL - the url where the swagger json specification is served from

Theme - the theme the ui should by displayed in

Themes

Themes, with exclusion of the default, are all sourced from swagger-ui-themes.

Development

To remove the need to keep static web ui files in the repository, this project uses statik to embed the swagger-ui-dist npm package into the project source.

A simple build script is included in the repository that can be used to resolve swagger-ui-dist from npm, copy and embed necessary files from the package. You will need to be running on a mac (macOS style sed is used) and have npm and statik installed in order for it to run.

Documentation

Index

• func NewHandler(options ...config.Option) http.Handler
• type Middleware
  • func New(options ...config.Option) Middleware

Functions

func NewHandler

func NewHandler(options ...config.Option) http.Handler

NewHandler returns an http.Handler that serves the swagger UI. This constructor ignores the `Path` option

Types

type Middleware

type Middleware func(next http.Handler) http.Handler

Middleware is a simple alias for a commonmiddle ware function signature, func(next http.Handler) http.Handler

func New

func New(options ...config.Option) Middleware

New is the factory constructor for intializing a middleware using config.Option funcs to override defaults settings