gin-swagger

gin middleware to automatically generate RESTful API documentation with Swagger 2.0.

Usage

Start using it

• Add comments to your API source code, See Declarative Comments Format.
• 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

• 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

• 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.

• 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") }

• Use swag init command to generate a docs, docs generated will be stored at docs/.
• import the docs like this:

I assume your project named github.com/go-project-name/docs.

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

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

• 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). | | DefaultModelExpandDepth | int | 1 | Default expansion depth for the model on the model-example section. | | DefaultModelRendering | string | "example" | Controls how the model is shown when the API is first rendered. "example" or "model". (The user can always switch the rendering for a given model by clicking the 'Model' and 'Example Value' links.) | | 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 clientid_ field of the OAuth2 Authorization dialog. | | Oauth2UsePkce | bool | false | If set to true, it enables Proof Key for Code Exchange to enhance security for OAuth public clients. |