swagger

README

Swagger for the Iris web framework

Iris middleware to automatically generate RESTful API documentation with Swagger 2.0 as requested at #1231.

Usage

Start using it

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

$ go install github.com/swaggo/swag/cmd/swag@latest

# if you find swag cli not work, you can try to install swag cli from source
git clone git@github.com:swaggo/swag.git
cd swag
# tag variable should match with github.com/swaggo/swag in go.mod
# here we use v1.8.10
git checkout -b ${tag} tags/${tag}
go install ./cmd/swag

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 for Iris by using:

$ go get github.com/iris-contrib/swagger/v12@master

And import following in your code:

import "github.com/Desdemo/fkiris-swagger"              // swagger middleware for Iris 
import "github.com/Desdemo/fkiris-swagger/swaggerFiles" // swagger embed files

Example Code:

package main

import (
	"github.com/8treenet/iris/v12"

	"github.com/Desdemo/fkiris-swagger"
	"github.com/Desdemo/fkiris-swagger/swaggerFiles"

	_ "github.com/your_username/your_project/docs"
	// docs folder should be generated by Swag CLI (swag init),
	// you have to import it.
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /v2
func main() {
	app := iris.New()

	swaggerUI := swagger.Handler(swaggerFiles.Handler,
		swagger.URL("/swagger/doc.json"),
		swagger.DeepLinking(true),
		swagger.Prefix("/swagger"),
	)

	// Register on http://localhost:8080/swagger
	app.Get("/swagger", swaggerUI)
	// And the wildcard one for index.html, *.js, *.css and e.t.c.
	app.Get("/swagger/{any:path}", swaggerUI)

	app.Listen(":8080")
}

1. Run it, and navigate through http://localhost:8080/swagger/index.html, you should see the Swagger 2.0 API documentation page.

2. If you want to disable swagger when some environment variable is set, use DisablingHandler instead of Handler.

swagger.DisablingHandler(swaggerFiles.Handler, "THE_OS_VARIABLE_NAME_HERE", configurators ...Configurator)

1. If you want to change swagger-ui theme, you can add swagger.SetTheme(swagger.Monokai) when init swaggerUI

swaggerUI := swagger.Handler(swaggerFiles.Handler,
swagger.URL("/swagger/doc.json"),
swagger.DeepLinking(true),
swagger.Prefix("/swagger"),
// ref: https://github.com/ostranme/swagger-ui-themes
// current we support 7 themes
// theme is a optional config, if you not set, it will use default theme
swagger.SetTheme(swagger.Monokai),
)

Documentation

Index

• Variables
• func DisablingHandler(h *webdav.Handler, envName string, configurators ...Configurator) iris.Handler
• func Handler(h *webdav.Handler, configurators ...Configurator) iris.Handler
• type Config
  • func (c Config) Configure(config *Config)
• type Configurator
• type ConfiguratorFunc
  • func DeepLinking(deepLinking bool) ConfiguratorFunc
  • func DefaultModelsExpandDepth(depth int) ConfiguratorFunc
  • func DocExpansion(docExpansion string) ConfiguratorFunc
  • func DomID(domID string) ConfiguratorFunc
  • func FontCDN(cdn string) ConfiguratorFunc
  • func OAuth(config *OAuthConfig) ConfiguratorFunc
  • func Oauth2DefaultClientID(oauth2DefaultClientID string) ConfiguratorFunc
  • func Oauth2UsePkce(usePkce bool) ConfiguratorFunc
  • func PersistAuthorization(persistAuthorization bool) ConfiguratorFunc
  • func Prefix(prefix string) ConfiguratorFunc
  • func SetTheme(theme Theme) ConfiguratorFunc
  • func SyntaxHighlight(syntaxHighlight bool) ConfiguratorFunc
  • func URL(url string) ConfiguratorFunc
  • func URLs(urls ...string) ConfiguratorFunc
  • func (fn ConfiguratorFunc) Configure(config *Config)
• type OAuthConfig
• type Theme
  • func (t Theme) IsValid() bool
  • func (t Theme) String() string

Variables

var (

	// DefaultConfig 默认的Swagger配置
	DefaultConfig = &Config{
		URL:          "swagger/swagger.json",
		DeepLinking:  true,
		DocExpansion: "list",
		DomID:        "#swagger-ui",
		Prefix:       "/swagger",
		FontCDN:      "https://fonts.googleapis.com",
		Theme:        Unknow,
		Filter:       true,
	}
)

Functions

func DisablingHandler

func DisablingHandler(h *webdav.Handler, envName string, configurators ...Configurator) iris.Handler

DisablingHandler turns handler off if specified environment variable passed.

func Handler

func Handler(h *webdav.Handler, configurators ...Configurator) iris.Handler

Handler wraps the webdav http handler into an Iris Handler one.

Usage:

swaggerUI := swagger.Handler(swaggerFiles.Handler,
 swagger.URL("http://localhost:8080/swagger/swagger.json"), // The url pointing to API definition))
 swagger.DeepLinking(true),
 swagger.Prefix("/swagger"),
)
app.Get("/swagger", swaggerUI)
app.Get("/swagger/{any:path}", swaggerUI)

OR

swaggerUI := swagger.Handler(swaggerFiles.Handler, swagger.Config{
 URL: ...,
 Prefix: ...,
 DeepLinking: ...,
 DocExpansion: ...,
 DomID: ...,
}

Types

type Config

type Config struct {
	// The URL pointing to API definition (normally swagger.json or swagger.yaml).
	// Default is `swagger/swagger.json`. DEPRECATED: Use URLs instead.
	URL string
	// The URLs pointing to API definitions (normally swagger.json or swagger.yaml).
	// Default is `["swagger/swagger.json"]`.
	URLs []string
	// The prefix url which this swagger ui is registered on.
	// Defaults to "/swagger". It can be a "." too.
	Prefix       string
	FontCDN      string
	Theme        Theme
	DeepLinking  bool
	DocExpansion string
	DomID        string
	// Enabling tag Filtering
	Filter bool
	// Persist authorization information over browser close/refresh
	PersistAuthorization bool
	// Syntax highlighting for the swagger UI
	SyntaxHighlight bool
	// Information for OAuth2 integration
	OAuth *OAuthConfig
	// Enable OAuth2 PKCE
	Oauth2UsePkce bool
	// Default OAuth2 client ID
	Oauth2DefaultClientID string
	// Default expansion depth for models
	DefaultModelsExpandDepth int
}

Config stores swagger configuration variables.

func (Config) Configure

func (c Config) Configure(config *Config)

Configure completes the Configurator interface. It allows to pass a Config as it is and override any option.

type Configurator

type Configurator interface {
	Configure(*Config)
}

Configurator represents a configuration setter.

type ConfiguratorFunc

type ConfiguratorFunc func(*Config)

ConfiguratorFunc implements the Configuration as a function type.

func DeepLinking

func DeepLinking(deepLinking bool) ConfiguratorFunc

DeepLinking set the swagger deeplinking configuration.

func DefaultModelsExpandDepth

func DefaultModelsExpandDepth(depth int) ConfiguratorFunc

DefaultModelsExpandDepth set the default expansion depth for models (set to -1 completely hide the models).

func DocExpansion

func DocExpansion(docExpansion string) ConfiguratorFunc

DocExpansion list, full, none.

func DomID

func DomID(domID string) ConfiguratorFunc

DomID #swagger-ui.

func FontCDN

func FontCDN(cdn string) ConfiguratorFunc

Change google font cdn to any you like.

func OAuth

func OAuth(config *OAuthConfig) ConfiguratorFunc

OAuth configure OAuth2 integration.

func Oauth2DefaultClientID

func Oauth2DefaultClientID(oauth2DefaultClientID string) ConfiguratorFunc

Oauth2DefaultClientID set the default client ID used for OAuth2.

func Oauth2UsePkce

func Oauth2UsePkce(usePkce bool) ConfiguratorFunc

Oauth2UsePkce enables Proof Key for Code Exchange. Corresponds to the usePkceWithAuthorizationCodeGrant property of the Swagger UI and applies only to accessCode (Authorization Code) flows.

func PersistAuthorization

func PersistAuthorization(persistAuthorization bool) ConfiguratorFunc

PersistAuthorization Persist authorization information over browser close/refresh. Defaults to false.

func Prefix

func Prefix(prefix string) ConfiguratorFunc

Prefix presents the URL prefix of this swagger UI (normally "/swagger" or ".").

func SetTheme

func SetTheme(theme Theme) ConfiguratorFunc

func SyntaxHighlight

func SyntaxHighlight(syntaxHighlight bool) ConfiguratorFunc

SyntaxHighlight enable syntax highlighting for the swagger UI. Defaults to false for backward compatibility.

func URL

func URL(url string) ConfiguratorFunc

URL presents the URL pointing to API definition (normally swagger.json or swagger.yaml). For backward compatibility - adds single URL to URLs slice.

func URLs

func URLs(urls ...string) ConfiguratorFunc

URLs presents the URLs pointing to API definitions (normally swagger.json or swagger.yaml).

func (ConfiguratorFunc) Configure

func (fn ConfiguratorFunc) Configure(config *Config)

Configure calls itself and modifies the default config.

type OAuthConfig

type OAuthConfig struct {
	// The ID of the client sent to the OAuth2 IAM provider.
	ClientId string
	// The OAuth2 realm that the client should operate in. If not applicable, use empty string.
	Realm string
	// The name to display for the application in the authentication popup.
	AppName string
}

OAuthConfig stores configuration for Swagger UI OAuth2 integration.

type Theme

type Theme string

const (
	FeelingBlue Theme = "feeling-blue"
	Material    Theme = "material"
	Muted       Theme = "muted"
	Outline     Theme = "outline"
	Flattop     Theme = "flattop"
	Monokai     Theme = "monokai"
	Newspaper   Theme = "newspaper"
	Unknow      Theme = "unknow"
)

func (Theme) IsValid

func (t Theme) IsValid() bool

func (Theme) String

func (t Theme) String() string