Home

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

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

4. 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 helloCall(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{"message": "Hello, You created a Web App!"})
}

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:

// helloCall godoc
// @Summary hellow example
// @Schemes
// @Description Hello
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Hello, You created a Web App!
// @Router / [get]
func helloCall(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{"message": "Hello, You created a Web App!"})
}

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

import (
   _ "github.com/vinodnextcoder/go-web-app/docs"
)

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

5. The full code and folder relatives here:

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "github.com/vinodnextcoder/go-web-app/docs"
)

// @title           Swagger Example API
// @version         1.0
// @description     This is a sample gin web server

// @contact.name   vinod
// @contact.url    http://www.swagger.io/support
// @contact.email  [email protected]

// @host      localhost:3001
// @BasePath  /

// @externalDocs.description  OpenAPI
// @externalDocs.url          https://swagger.io/resources/open-api/
func main() {

	router := gin.Default()

	router.GET("/", helloCall)

	router.GET("/about", aboutCall)
	router.GET("/user/:name", getUser)
	router.GET("/user", getUsers)
	router.POST("/user", addUser)
	router.GET("/userData/:id", getUserByID)
	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	router.Run(":3001")
}

Demo project tree, swag init is run at relative .

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