swagger

README

Swagger

fiber middleware to automatically generate RESTful API documentation with Swagger

Usage

1. Add comments to your API source code, See Declarative Comments Format.
2. Download Swag for Go by using:

go get -u github.com/swaggo/swag/cmd/swag
# 1.16 or newer
go install github.com/swaggo/swag/cmd/swag@latest

1. Run the Swag in your Go project root folder which contains main.go file, Swag will parse comments and generate required files(docs folder and docs/doc.go).

swag init

1. Download swagger by using:

go get -u github.com/gofiber/swagger

And import following in your code:

import "github.com/gofiber/swagger" // swagger handler

Canonical example:

package main

import (
	"github.com/gofiber/swagger"
	"github.com/gofiber/fiber/v2"

	// docs are generated by Swag CLI, you have to import them.
	// replace with your own docs folder, usually "github.com/username/reponame/docs"
	_ "github.com/gofiber/swagger/example/docs"
)

// @title Fiber Example API
// @version 1.0
// @description This is a sample swagger for Fiber
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.email fiber@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /
func main() {
	app := fiber.New()

	app.Get("/swagger/*", swagger.HandlerDefault) // default

	app.Get("/swagger/*", swagger.New(swagger.Config{ // custom
		URL: "http://example.com/doc.json",
		DeepLinking: false,
		// Expand ("list") or Collapse ("none") tag groups by default
		DocExpansion: "none",
		// Prefill OAuth ClientId on Authorize popup
		OAuth: &swagger.OAuthConfig{
			AppName:  "OAuth Provider",
			ClientId: "21bb4edc-05a7-4afc-86f1-2e151e4ba6e2",
		},
		// Ability to change OAuth2 redirect uri location
		OAuth2RedirectUrl: "http://localhost:8080/swagger/oauth2-redirect.html",
	}))

	app.Listen(":8080")
}

1. Run it, and browser to http://localhost:8080/swagger, you can see Swagger 2.0 Api documents.

Documentation

Index

• Variables
• func New(config ...Config) fiber.Handler
• type Config
• type FilterConfig
  • func (fc FilterConfig) Value() interface{}
• type OAuthConfig
• type SyntaxHighlightConfig
  • func (shc SyntaxHighlightConfig) Value() interface{}

Variables

var (
	ConfigDefault = Config{
		Title:  "Swagger UI",
		Layout: "StandaloneLayout",
		Plugins: []template.JS{
			template.JS("SwaggerUIBundle.plugins.DownloadUrl"),
		},
		Presets: []template.JS{
			template.JS("SwaggerUIBundle.presets.apis"),
			template.JS("SwaggerUIStandalonePreset"),
		},
		DeepLinking:              true,
		DefaultModelsExpandDepth: 1,
		DefaultModelExpandDepth:  1,
		DefaultModelRendering:    "example",
		DocExpansion:             "list",
		SyntaxHighlight: &SyntaxHighlightConfig{
			Activate: true,
			Theme:    "agate",
		},
		ShowMutatedRequest: true,
	}
)

var HandlerDefault = New()

Functions

func New

func New(config ...Config) fiber.Handler

New returns custom handler

Types

type Config

type Config struct {
	// This parameter can be used to name different swagger document instances.
	// default: ""
	InstanceName string `json:"-"`

	// Title pointing to title of HTML page.
	// default: "Swagger UI"
	Title string `json:"-"`

	// URL to fetch external configuration document from.
	// default: ""
	ConfigURL string `json:"configUrl,omitempty"`

	// The URL pointing to API definition (normally swagger.json or swagger.yaml).
	// default: "doc.json"
	URL string `json:"url,omitempty"`

	// Enables overriding configuration parameters via URL search params.
	// default: false
	QueryConfigEnabled bool `json:"queryConfigEnabled,omitempty"`

	// The name of a component available via the plugin system to use as the top-level layout for Swagger UI.
	// default: "StandaloneLayout"
	Layout string `json:"layout,omitempty"`

	// An array of plugin functions to use in Swagger UI.
	// default: [SwaggerUIBundle.plugins.DownloadUrl]
	Plugins []template.JS `json:"-"`

	// An array of presets to use in Swagger UI. Usually, you'll want to include ApisPreset if you use this option.
	// default: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset]
	Presets []template.JS `json:"-"`

	// If set to true, enables deep linking for tags and operations.
	// default: true
	DeepLinking bool `json:"deepLinking"`

	// Controls the display of operationId in operations list.
	// default: false
	DisplayOperationId bool `json:"displayOperationId,omitempty"`

	// The default expansion depth for models (set to -1 completely hide the models).
	// default: 1
	DefaultModelsExpandDepth int `json:"defaultModelsExpandDepth,omitempty"`

	// The default expansion depth for the model on the model-example section.
	// default: 1
	DefaultModelExpandDepth int `json:"defaultModelExpandDepth,omitempty"`

	// Controls how the model is shown when the API is first rendered.
	// The user can always switch the rendering for a given model by clicking the 'Model' and 'Example Value' links.
	// default: "example"
	DefaultModelRendering string `json:"defaultModelRendering,omitempty"`

	// Controls the display of the request duration (in milliseconds) for "Try it out" requests.
	// default: false
	DisplayRequestDuration bool `json:"displayRequestDuration,omitempty"`

	// Controls the default expansion setting for the operations and tags.
	// 'list' (default, expands only the tags),
	// 'full' (expands the tags and operations),
	// 'none' (expands nothing)
	DocExpansion string `json:"docExpansion,omitempty"`

	// If set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown.
	// Can be Boolean to enable or disable, or a string, in which case filtering will be enabled using that string as the filter expression.
	// Filtering is case sensitive matching the filter expression anywhere inside the tag.
	// default: false
	Filter FilterConfig `json:"-"`

	// If set, limits the number of tagged operations displayed to at most this many. The default is to show all operations.
	// default: 0
	MaxDisplayedTags int `json:"maxDisplayedTags,omitempty"`

	// Controls the display of vendor extension (x-) fields and values for Operations, Parameters, Responses, and Schema.
	// default: false
	ShowExtensions bool `json:"showExtensions,omitempty"`

	// Controls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields and values for Parameters.
	// default: false
	ShowCommonExtensions bool `json:"showCommonExtensions,omitempty"`

	// Apply a sort to the tag list of each API. It can be 'alpha' (sort by paths alphanumerically) or a function (see Array.prototype.sort().
	// to learn how to write a sort function). Two tag name strings are passed to the sorter for each pass.
	// default: "" -> Default is the order determined by Swagger UI.
	TagsSorter template.JS `json:"-"`

	// Provides a mechanism to be notified when Swagger UI has finished rendering a newly provided definition.
	// default: "" -> Function=NOOP
	OnComplete template.JS `json:"-"`

	// An object with the activate and theme properties.
	SyntaxHighlight *SyntaxHighlightConfig `json:"-"`

	// Controls whether the "Try it out" section should be enabled by default.
	// default: false
	TryItOutEnabled bool `json:"tryItOutEnabled,omitempty"`

	// Enables the request snippet section. When disabled, the legacy curl snippet will be used.
	// default: false
	RequestSnippetsEnabled bool `json:"requestSnippetsEnabled,omitempty"`

	// OAuth redirect URL.
	// default: ""
	OAuth2RedirectUrl string `json:"oauth2RedirectUrl,omitempty"`

	// MUST be a function. Function to intercept remote definition, "Try it out", and OAuth 2.0 requests.
	// Accepts one argument requestInterceptor(request) and must return the modified request, or a Promise that resolves to the modified request.
	// default: ""
	RequestInterceptor template.JS `json:"-"`

	// If set, MUST be an array of command line options available to the curl command. This can be set on the mutated request in the requestInterceptor function.
	// For example request.curlOptions = ["-g", "--limit-rate 20k"]
	// default: nil
	RequestCurlOptions []string `json:"request.curlOptions,omitempty"`

	// MUST be a function. Function to intercept remote definition, "Try it out", and OAuth 2.0 responses.
	// Accepts one argument responseInterceptor(response) and must return the modified response, or a Promise that resolves to the modified response.
	// default: ""
	ResponseInterceptor template.JS `json:"-"`

	// If set to true, uses the mutated request returned from a requestInterceptor to produce the curl command in the UI,
	// otherwise the request before the requestInterceptor was applied is used.
	// default: true
	ShowMutatedRequest bool `json:"showMutatedRequest"`

	// List of HTTP methods that have the "Try it out" feature enabled. An empty array disables "Try it out" for all operations.
	// This does not filter the operations from the display.
	// Possible values are ["get", "put", "post", "delete", "options", "head", "patch", "trace"]
	// default: nil
	SupportedSubmitMethods []string `json:"supportedSubmitMethods,omitempty"`

	// By default, Swagger UI attempts to validate specs against swagger.io's online validator. You can use this parameter to set a different validator URL.
	// For example for locally deployed validators (https://github.com/swagger-api/validator-badge).
	// Setting it to either none, 127.0.0.1 or localhost will disable validation.
	// default: ""
	ValidatorUrl string `json:"validatorUrl,omitempty"`

	// If set to true, enables passing credentials, as defined in the Fetch standard, in CORS requests that are sent by the browser.
	// Note that Swagger UI cannot currently set cookies cross-domain (see https://github.com/swagger-api/swagger-js/issues/1163).
	// as a result, you will have to rely on browser-supplied cookies (which this setting enables sending) that Swagger UI cannot control.
	// default: false
	WithCredentials bool `json:"withCredentials,omitempty"`

	// Function to set default values to each property in model. Accepts one argument modelPropertyMacro(property), property is immutable.
	// default: ""
	ModelPropertyMacro template.JS `json:"-"`

	// Function to set default value to parameters. Accepts two arguments parameterMacro(operation, parameter).
	// Operation and parameter are objects passed for context, both remain immutable.
	// default: ""
	ParameterMacro template.JS `json:"-"`

	// If set to true, it persists authorization data and it would not be lost on browser close/refresh.
	// default: false
	PersistAuthorization bool `json:"persistAuthorization,omitempty"`

	// Configuration information for OAuth2, optional if using OAuth2
	OAuth *OAuthConfig `json:"-"`

	// (authDefinitionKey, username, password) => action
	// Programmatically set values for a Basic authorization scheme.
	// default: ""
	PreauthorizeBasic template.JS `json:"-"`

	// (authDefinitionKey, apiKeyValue) => action
	// Programmatically set values for an API key or Bearer authorization scheme.
	// In case of OpenAPI 3.0 Bearer scheme, apiKeyValue must contain just the token itself without the Bearer prefix.
	// default: ""
	PreauthorizeApiKey template.JS `json:"-"`

	// Applies custom CSS styles.
	// default: ""
	CustomStyle template.CSS `json:"-"`

	// Applies custom JavaScript scripts.
	// default ""
	CustomScript template.JS `json:"-"`
}

Config stores SwaggerUI configuration variables

type FilterConfig

type FilterConfig struct {
	Enabled    bool
	Expression string
}

func (FilterConfig) Value

func (fc FilterConfig) Value() interface{}

type OAuthConfig

type OAuthConfig struct {
	// ID of the client sent to the OAuth2 provider.
	// default: ""
	ClientId string `json:"clientId,omitempty"`

	// Never use this parameter in your production environment.
	// It exposes cruicial security information. This feature is intended for dev/test environments only.
	// Secret of the client sent to the OAuth2 provider.
	// default: ""
	ClientSecret string `json:"clientSecret,omitempty"`

	// Application name, displayed in authorization popup.
	// default: ""
	AppName string `json:"appName,omitempty"`

	// Realm query parameter (for oauth1) added to authorizationUrl and tokenUrl.
	// default: ""
	Realm string `json:"realm,omitempty"`

	// String array of initially selected oauth scopes
	// default: nil
	Scopes []string `json:"scopes,omitempty"`

	// Additional query parameters added to authorizationUrl and tokenUrl.
	// default: nil
	AdditionalQueryStringParams map[string]string `json:"additionalQueryStringParams,omitempty"`

	// Unavailable	Only activated for the accessCode flow.
	// During the authorization_code request to the tokenUrl, pass the Client Password using the HTTP Basic Authentication scheme
	// (Authorization header with Basic base64encode(client_id + client_secret)).
	// default: false
	UseBasicAuthenticationWithAccessCodeGrant bool `json:"useBasicAuthenticationWithAccessCodeGrant,omitempty"`

	// Only applies to authorizatonCode flows.
	// Proof Key for Code Exchange brings enhanced security for OAuth public clients.
	// default: false
	UsePkceWithAuthorizationCodeGrant bool `json:"usePkceWithAuthorizationCodeGrant,omitempty"`
}

type SyntaxHighlightConfig

type SyntaxHighlightConfig struct {
	// Whether syntax highlighting should be activated or not.
	// default: true
	Activate bool `json:"activate"`
	// Highlight.js syntax coloring theme to use.
	// Possible values are ["agate", "arta", "monokai", "nord", "obsidian", "tomorrow-night"]
	// default: "agate"
	Theme string `json:"theme,omitempty"`
}

func (SyntaxHighlightConfig) Value

func (shc SyntaxHighlightConfig) Value() interface{}