ginSwagger

README

gin-swagger

gin middleware to automatically 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 -u github.com/swaggo/swag/cmd/swag

Starting in Go 1.17, installing executables with go get is deprecated. go install may be used instead:

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

1. Run the Swag at your Go project root path(for instance ~/root/go-project-name), Swag will parse comments and generate required files(docs folder and docs/doc.go) at ~/root/go-project-name/docs.

swag init

1. Download gin-swagger by using:

go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

Import following in your code:

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
import "github.com/swaggo/files" // swagger embed files

Canonical example:

Now assume you have implemented a simple api as following:

// A get function which returns a hello world string by json
func Helloworld(g *gin.Context)  {
	g.JSON(http.StatusOK,"helloworld")
}

So how to use gin-swagger on api above? Just follow the following guide.

1. Add Comments for apis and main function with gin-swagger rules like following:

// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
	g.JSON(http.StatusOK,"helloworld")
}

1. Use swag init command to generate a docs, docs generated will be stored at docs/.
2. import the docs like this: I assume your project named github.com/go-project-name/docs.

import (
   docs "github.com/go-project-name/docs"
)

1. build your application and after that, go to http://localhost:8080/swagger/index.html ,you to see your Swagger UI.

2. The full code and folder relatives here:

package main

import (
   "github.com/gin-gonic/gin"
   docs "github.com/go-project-name/docs"
   swaggerfiles "github.com/swaggo/files"
   ginSwagger "github.com/swaggo/gin-swagger"
   "net/http"
)
// @BasePath /api/v1

// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context)  {
   g.JSON(http.StatusOK,"helloworld")
}

func main()  {
   r := gin.Default()
   docs.SwaggerInfo.BasePath = "/api/v1"
   v1 := r.Group("/api/v1")
   {
      eg := v1.Group("/example")
      {
         eg.GET("/helloworld",Helloworld)
      }
   }
   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
   r.Run(":8080")

}

Demo project tree, swag init is run at relative .

.
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
└── main.go

Project with Nested Directory

.
├── cmd
│   └── ginsimple
│       └── main.go
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
└── internal
    ├── handlers
    │   ├── helloWorld.go
    │   └── userHandler.go
    └── models
        ├── profile.go
        └── user.go

Inorder generate swagger docs for projects with nested directories run the following command

swag init -g ./cmd/ginsimple/main.go -o cmd/docs

-o will set the auto generated file to the specified path

Multiple APIs

This feature was introduced in swag v1.7.9

Configuration

You can configure Swagger using different configuration options

func main() {
	r := gin.New()

	ginSwagger.WrapHandler(swaggerfiles.Handler,
		ginSwagger.URL("http://localhost:8080/swagger/doc.json"),
		ginSwagger.DefaultModelsExpandDepth(-1))

	r.Run()
}

Option	Type	Default	Description
URL	string	"doc.json"	URL pointing to API definition
DocExpansion	string	"list"	Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing).
DeepLinking	bool	true	If set to true, enables deep linking for tags and operations. See the Deep Linking documentation for more information.
DefaultModelsExpandDepth	int	1	Default expansion depth for models (set to -1 completely hide the models).
InstanceName	string	"swagger"	The instance name of the swagger document. If multiple different swagger instances should be deployed on one gin router, ensure that each instance has a unique name (use the --instanceName parameter to generate swagger documents with swag init).
PersistAuthorization	bool	false	If set to true, it persists authorization data and it would not be lost on browser close/refresh.
Oauth2DefaultClientID	string	""	If set, it's used to prepopulate the client_id field of the OAuth2 Authorization dialog.
UsePkceWithAuthorizationCodeGrant	bool	false	If set to true, it enables Proof Key for Code Exchange to enhance security for OAuth public clients.

Documentation

Index

• func CustomWrapHandler(config *Config, handler *webdav.Handler) gin.HandlerFunc
• func DeepLinking(deepLinking bool) func(*Config)
• func DefaultModelsExpandDepth(depth int) func(*Config)
• func DisablingCustomWrapHandler(config *Config, handler *webdav.Handler, envName string) gin.HandlerFunc
• func DisablingWrapHandler(handler *webdav.Handler, envName string) gin.HandlerFunc
• 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 URL(url string) func(*Config)
• func UsePkceWithAuthorizationCodeGrant(usePkce bool) func(*Config)
• func WrapHandler(handler *webdav.Handler, options ...func(*Config)) gin.HandlerFunc
• type Config

Functions

func CustomWrapHandler

func CustomWrapHandler(config *Config, handler *webdav.Handler) gin.HandlerFunc

CustomWrapHandler wraps `http.Handler` into `gin.HandlerFunc`.

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) gin.HandlerFunc

DisablingCustomWrapHandler turn handler off if specified environment variable passed.

func DisablingWrapHandler

func DisablingWrapHandler(handler *webdav.Handler, envName string) gin.HandlerFunc

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 URL

func URL(url string) func(*Config)

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

func UsePkceWithAuthorizationCodeGrant

func UsePkceWithAuthorizationCodeGrant(usePkce bool) func(*Config)

UsePkceWithAuthorizationCodeGrant enables Proof Key for Code Exchange. Only applies to accessCode (Authorization Code) flows.

func WrapHandler

func WrapHandler(handler *webdav.Handler, options ...func(*Config)) gin.HandlerFunc

WrapHandler wraps `http.Handler` into `gin.HandlerFunc`.

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
	UsePkceWithAuthorizationCodeGrant bool
}

Config stores ginSwagger configuration variables.