swaggerui

README

SwaggerUI Handler For Gin

This project implements a gin Handler which allows you to expose your OpenAPI spec via SwaggerUI.

Installing

go get github.com/DEXPRO-Solutions-GmbH/swaggerui

Documentation

Overview

Package swaggerui allows you to serve a Swagger UI.

The subdirectory dist contains a prebuild version of the Swagger UI taken from the official Github page.

Index

• type Handler
  • func NewHandler(specYML []byte, opts ...Option) (*Handler, error)
  • func (handler *Handler) GetSpec(ctx *gin.Context)
  • func (handler *Handler) Register(router gin.IRoutes)
• type HandlerMiddleware
• type Option
  • func WithAddServerUrls() Option
  • func WithMiddleware(mw HandlerMiddleware) Option
  • func WithOIDC(securitySchemeName, oidcURL string) Option
  • func WithReplaceServerUrls() Option
• type Spec
  • func ParseSpecYAML(raw []byte) (Spec, error)
  • func (spec Spec) AddServerUrl(serverUrl string)
  • func (spec Spec) RemoveServerURLs()
  • func (spec Spec) SetOpenIdConnectUrl(securitySchemeName string, url string)

Types

type Handler

type Handler struct {
	FS http.FileSystem
	// contains filtered or unexported fields
}

Handler is responsible for both serving the SwaggerUI and the associated OpenAPI spec.

func NewHandler

func NewHandler(specYML []byte, opts ...Option) (*Handler, error)

NewHandler returns a new Handler based on the given spec. It is expected that the given data contains valid YAML.

func (*Handler) GetSpec

func (handler *Handler) GetSpec(ctx *gin.Context)

GetSpec is the gin handler function used to serve the OpenAPI spec of this handler.

func (*Handler) Register

func (handler *Handler) Register(router gin.IRoutes)

Register is used to register the Handler on a gin router.

type HandlerMiddleware

type HandlerMiddleware func(ctx *gin.Context, spec Spec)

A HandlerMiddleware can modify the given Spec. You may use the gin.Context if you require any information from the request.

type Option

type Option func(handler *Handler)

Option objects used to construct Handler objects.

func WithAddServerUrls

func WithAddServerUrls() Option

WithAddServerUrls adds a HandlerMiddleware which adds the requests host to the OpenAPI specs server list, once with HTTP, once with HTTPS.

This is meant to be used on APIs which could be served under any hostname and where you don't want to hardcode the hostname in your spec.

func WithMiddleware

func WithMiddleware(mw HandlerMiddleware) Option

WithMiddleware applies the given HandlerMiddleware to every request.

func WithOIDC

func WithOIDC(securitySchemeName, oidcURL string) Option

WithOIDC adds a HandlerMiddleware which replaces the OpenIDConnect URL of a given security scheme with the given url. This is useful if your API is secured by an OIDC provider and you want to make the provider your API trusts configurable.

func WithReplaceServerUrls

func WithReplaceServerUrls() Option

WithReplaceServerUrls is the same as WithAddServerUrls but it will replace all previously defined server urls.

type Spec

type Spec map[string]any

Spec is a custom type used to represent a swagger spec. It is mostly unvalidated and not more type-safe than a regular map[string]any, but it allows us to add custom methods.

Nested objects are also expected to be of type Spec.

func ParseSpecYAML

func ParseSpecYAML(raw []byte) (Spec, error)

func (Spec) AddServerUrl

func (spec Spec) AddServerUrl(serverUrl string)

AddServerUrl adds a url element to the servers list. The last url added will be the first one to be displayed in the Swagger UI, making it the default server.

func (Spec) RemoveServerURLs

func (spec Spec) RemoveServerURLs()

RemoveServerURLs removes all server urls and removes the servers key.

func (Spec) SetOpenIdConnectUrl

func (spec Spec) SetOpenIdConnectUrl(securitySchemeName string, url string)

SetOpenIdConnectUrl replaces the url of a given OpenID Connect security scheme.

This method panics if any keys of the underlying Spec don't exist or are not of type Spec.

This method also panics if the given scheme is not of type "openIdConnect".