Gin + Swagger-526互联

Gin 集成 Swagger , GitHub - swaggo/gin-swagger: gin middleware to automatically generate RESTful API documentation with Swagger 2.0.

下载 Swagger

go get -u github.com/swaggo/swag/cmd/swag

生成 swag.exe, 在 GOPATH / bin

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

在项目根目录，打开终端，执行
1. ```
swag init
```
2. 执行完之后，会生成如下文件

下载 gin-swagger

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

Import

// 这三种不可少
import (
	_ "Gin_Study/docs"
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

在路由定义swagger 的路径

	// 定义swagger 的路径，首页是 /swagger/index.html
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

Full Code

package main

import (
	_ "Gin_Study/docs"

	"net/http"

	"github.com/gin-gonic/gin"
	swaggerfiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /v1/ping [get]
func v1Pong(ctx *gin.Context) {
	ctx.JSON(http.StatusOK, gin.H{"message": "hello"})
}

// @title			Swagger Example API
// @version			1.0
// @description	Gin Swagger 测试
func main() {

	// gin.SetMode(gin.ReleaseMode)

	r := gin.Default()

	// 定义swagger 的路径，首页是 /swagger/index.html
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

	r.SetTrustedProxies([]string{"localhost"})

	v1 := r.Group("/v1")
	{
		v1.GET("/ping", v1Pong)
	}

	v2 := r.Group("/v2")
	{
		v2.GET("/ping", func(ctx *gin.Context) {
			ctx.JSON(http.StatusOK, gin.H{"message": "hello"})
		})
	}

	r.Run(":8080")
}

运行Gin，并在浏览器访问 Swagger UI
具体的注释参数，还要参考 Git Hub 里面的内容，每次修改注释后，都要执行
1. 　　
```
swag init
```

小结：

Swagger 其实就是通过注释，生成对应的API。如果只改了代码，而不修改注释，Swagger 是不会发生变化的，从这个角度出发，程序猿既要维护代码，又要维护注释了，这算不算给自己挖了一个坑？？？

Swagger

Gin

gin-swagger

gin-swagger swagger golang gin