swag

README

stgin-swagger

stgin add-on library to generate RESTful API documentation with Swagger 2.0.

Usage

Start using it

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

$ go get -d 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 stgin-swag by using:

$ go get -u github.com/AminMal/stgin-swag

And import following in your code:

import swag "github.com/AminMal/stgin-swag"

After (not necessarily) adding routes to the server, you can use this utility function called ServedOnPrefix, to add swagger to your server.

server.AddRoutes(...)
swag.ServedOnPrefix("/swagger", server, myCustomOptions...)

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

Documentation

Index

• func CustomWrapHandler(config *Config, handler *webdav.Handler) stgin.API
• func DeepLinking(deepLinking bool) func(*Config)
• func DefaultModelsExpandDepth(depth int) func(*Config)
• func DisablingCustomWrapHandler(config *Config, handler *webdav.Handler, envName string) stgin.API
• func DisablingWrapHandler(handler *webdav.Handler, envName string) stgin.API
• func DocExpansion(docExpansion string) func(*Config)
• func InstanceName(name string) func(*Config)
• func Oauth2DefaultClientID(oauth2DefaultClientID string) func(*Config)
• func PersistAuthorization(persistAuthorization bool) func(*Config)
• func ServedOnPrefix(prefix string, server *stgin.Server, options ...func(*Config))
• func URL(url string) func(*Config)
• func WrapHandler(handler *webdav.Handler, options ...func(*Config)) stgin.API
• type Config

Functions

func CustomWrapHandler

func CustomWrapHandler(config *Config, handler *webdav.Handler) stgin.API

CustomWrapHandler wraps `http.Handler` into `stgin.API`.

func DeepLinking

func DeepLinking(deepLinking bool) func(*Config)

DeepLinking set the swagger deep linking configuration.

func DefaultModelsExpandDepth

func DefaultModelsExpandDepth(depth int) func(*Config)

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

func DisablingCustomWrapHandler

func DisablingCustomWrapHandler(config *Config, handler *webdav.Handler, envName string) stgin.API

DisablingCustomWrapHandler turn handler off if specified environment variable passed.

func DisablingWrapHandler

func DisablingWrapHandler(handler *webdav.Handler, envName string) stgin.API

DisablingWrapHandler turn handler off if specified environment variable passed.

func DocExpansion

func DocExpansion(docExpansion string) func(*Config)

DocExpansion list, full, none.

func InstanceName

func InstanceName(name string) func(*Config)

InstanceName set the instance name that was used to generate the swagger documents Defaults to swag.Name ("swagger").

func Oauth2DefaultClientID

func Oauth2DefaultClientID(oauth2DefaultClientID string) func(*Config)

Oauth2DefaultClientID set the default client ID used for OAuth2

func PersistAuthorization

func PersistAuthorization(persistAuthorization bool) func(*Config)

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

func ServedOnPrefix

func ServedOnPrefix(prefix string, server *stgin.Server, options ...func(*Config))

func URL

func URL(url string) func(*Config)

URL presents the url pointing to API definition (normally swagger.json or swagger.yaml).

func WrapHandler

func WrapHandler(handler *webdav.Handler, options ...func(*Config)) stgin.API

WrapHandler wraps `http.Handler` into `stgin.API`.

Types

type Config

type Config struct {
	// The url pointing to API definition (normally swagger.json or swagger.yaml). Default is `doc.json`.
	URL                      string
	DocExpansion             string
	InstanceName             string
	Title                    string
	DefaultModelsExpandDepth int
	DeepLinking              bool
	PersistAuthorization     bool
	Oauth2DefaultClientID    string
}

Config stores stginSwagger configuration variables.