docui

Documentation

Overview

Package docui provides standalone HTTP middlewares that serve OpenAPI documentation UIs (Swagger UI, ReDoc, RapiDoc) and the spec document itself.

The package is stdlib-only and has no transitive dependency on any OpenAPI spec, loading or validation library, so it may be imported by any net/http application that simply wants to mount a documentation site.

Index

• func RapiDoc(next http.Handler, opts ...Option) http.Handler
• func Redoc(next http.Handler, opts ...Option) http.Handler
• func ServeSpec(spec []byte, next http.Handler, opts ...SpecOption) http.Handler
• func SwaggerUI(next http.Handler, opts ...Option) http.Handler
• func SwaggerUIOAuth2Callback(next http.Handler, opts ...Option) http.Handler
• func UseRapiDoc(opts ...Option) func(next http.Handler) http.Handler
• func UseRedoc(opts ...Option) func(next http.Handler) http.Handler
• func UseSpec(spec []byte, opts ...SpecOption) func(next http.Handler) http.Handler
• func UseSwaggerUI(opts ...Option) func(next http.Handler) http.Handler
• func UseSwaggerUIOAuth2Callback(opts ...Option) func(next http.Handler) http.Handler
• type Option
  • func WithSpecURL(u string) Option
  • func WithSwaggerUIOptions(opts SwaggerUIOptions) Option
  • func WithUIAssetsURL(assets string) Option
  • func WithUIBasePath(base string) Option
  • func WithUIPath(pth string) Option
  • func WithUITemplate[StringOrBytes ~string | ~[]byte](tpl StringOrBytes) Option
  • func WithUITitle(title string) Option
• type SpecOption
  • func WithSpecPath(pth string) SpecOption
  • func WithSpecPathFromOptions(opts ...Option) SpecOption
• type SwaggerUIOptions
• type UIMiddleware

Functions

func RapiDoc

func RapiDoc(next http.Handler, opts ...Option) http.Handler

RapiDoc creates a http.Handler to serve a documentation site for a swagger spec using [RapidDoc].

By default, the UI is served at route "/docs"

This allows for altering the spec before starting the http listener.

func Redoc

func Redoc(next http.Handler, opts ...Option) http.Handler

Redoc creates a http.Handler to serve a documentation site for a swagger spec using Redoc.

By default, the UI is served at route "/docs"

This allows for altering the spec before starting the http listener.

func ServeSpec

func ServeSpec(spec []byte, next http.Handler, opts ...SpecOption) http.Handler

ServeSpec creates a http.Handler to serve a swagger spec as a JSON document.

This allows for altering the spec before starting the http listener.

Additional SpecOption can be used to change the path and the name of the document (defaults to "/swagger.json").

func SwaggerUI

func SwaggerUI(next http.Handler, opts ...Option) http.Handler

SwaggerUI creates a http.Handler to serve a documentation site for a swagger spec using SwaggerUI.

By default, the UI is served at route "/docs"

This allows for altering the spec before starting the http listener.

func SwaggerUIOAuth2Callback

func SwaggerUIOAuth2Callback(next http.Handler, opts ...Option) http.Handler

SwaggerUIOAuth2Callback creates a http.Handler that serves a callback URL to complete a OAuth2 token handshake.

func UseRapiDoc

func UseRapiDoc(opts ...Option) func(next http.Handler) http.Handler

UseRapiDoc creates a middleware to serve a documentation site for a swagger spec using [RapidDoc].

func UseRedoc

func UseRedoc(opts ...Option) func(next http.Handler) http.Handler

UseRedoc creates a middleware to serve a documentation site for a swagger spec using Redoc.

func UseSpec

func UseSpec(spec []byte, opts ...SpecOption) func(next http.Handler) http.Handler

UseSpec creates a middleware to serve a swagger spec as a JSON document.

func UseSwaggerUI

func UseSwaggerUI(opts ...Option) func(next http.Handler) http.Handler

UseSwaggerUI creates a middleware to serve a documentation site for a swagger spec using SwaggerUI.

func UseSwaggerUIOAuth2Callback

func UseSwaggerUIOAuth2Callback(opts ...Option) func(next http.Handler) http.Handler

UseSwaggerUIOAuth2Callback creates a middleware that serves a callback URL to complete a OAuth2 token handshake.

Types

type Option

type Option func(*options)

Option to tune your swagger documentation UI middleware.

Options may be combined to alter the route at which the UI asset is served, the URL of the spec document, the source URL of the UI asset and the title of the UI page.

The embedded js scriptlet served may be modified using WithUITemplate.

func WithSpecURL

func WithSpecURL(u string) Option

WithSpecURL sets the URL of the spec document.

Defaults to: /swagger.json

func WithSwaggerUIOptions

func WithSwaggerUIOptions(opts SwaggerUIOptions) Option

func WithUIAssetsURL

func WithUIAssetsURL(assets string) Option

WithUIAssetsURL sets the URL from where to fetch the js assets.

Defaults:

• for Redoc: https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js
• for RapiDoc, this defaults to: https://unpkg.com/rapidoc/dist/rapidoc-min.js
• for SwaggerUI: https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js

func WithUIBasePath

func WithUIBasePath(base string) Option

WithUIBasePath sets the base path from where to serve the UI assets.

Default: "/"

func WithUIPath

func WithUIPath(pth string) Option

WithUIPath sets the path from where to serve the UI assets (i.e. /{basepath}/{path}).

Default: "docs"

func WithUITemplate

func WithUITemplate[StringOrBytes ~string | ~[]byte](tpl StringOrBytes) Option

WithUITemplate allows to set a custom template for the UI.

This allows the caller to fully customize the rendered UI, using the advanced options provided by any UI.

The UI [middleware] will panic if the template does not parse or execute properly.

Reference documentations to customize your js scriptlet:

• for Redoc: https://github.com/Redocly/redoc/blob/main/docs/deployment/html.md
• for RapiDoc: https://github.com/rapi-doc/RapiDoc
• for SwaggerUI: https://github.com/swagger-api/swagger-ui

func WithUITitle

func WithUITitle(title string) Option

WithUITitle sets the title of the UI.

Default: "API documentation"

type SpecOption

type SpecOption func(*specOptions)

SpecOption can be applied to the ServeSpec middleware.

func WithSpecPath

func WithSpecPath(pth string) SpecOption

WithSpecPath sets the path of the spec document.

This is "/swagger.json" by default.

func WithSpecPathFromOptions

func WithSpecPathFromOptions(opts ...Option) SpecOption

WithSpecPathFromOptions reuses the same SpecPath as the one specified in a set of UI Option (extract the path from the URL provided by WithSpecURL).

type SwaggerUIOptions

type SwaggerUIOptions struct {
	// OAuth2CallbackURL sets the URL called after OAuth2 login
	OAuth2CallbackURL string

	// Defines the URL of the swagger UI assets with presets.
	//
	// Default: https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js
	SwaggerPresetURL string

	// Defines style sheet URL.
	//
	// Default: https://unpkg.com/swagger-ui-dist/swagger-ui.css
	SwaggerStylesURL string

	// Define the favicons URLs.
	//
	// Defaults:
	//
	//   - 16x16: https://unpkg.com/swagger-ui-dist/favicon-16x16.png
	//   - 32x32: https://unpkg.com/swagger-ui-dist/favicon-32x32.png
	Favicon32 string
	Favicon16 string
}

SwaggerUIOptions define a group of extra options specific to the SwaggerUI component.

type UIMiddleware

type UIMiddleware func(...Option) func(http.Handler) http.Handler

UIMiddleware is a function returning a http middleware which accepts UI Option.