为基于Gin的Web项目生成Swagger在线API文档

安装swag命令

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

注意:

确保提前配置了Go环境.

# Go
GOPATH=$HOME/go
GOBIN=$GOPATH/bin
PATH="$GOBIN:$PATH"
GOPROXY=https://goproxy.io
export GOPATH GOBIN PATH GOPROXY

验证是否安装成功:

swag -v

安装gin-swagger

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

为swagger添加访问路由

配置文件: conf/config.yaml

# 设置用于是否开启swagger的环境变量名称, 在启动server之前设置该环境变量的值,
# 如果环境变量SWAGGER的值为空, 则默认启用swagger, 如果不为空, 则不启用swagger,
# 访问/swagger/index.html将返回404错误.
swagger_env: SWAGGER

路由文件: router/router.go

package router

import (
	"net/http"

	_ "yourapp/docs"

	"github.com/gin-gonic/gin"
	"github.com/spf13/viper"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

// 加载中间件、路由、处理函数.
func Load(g *gin.Engine, mw ...gin.HandlerFunc) {
	// Middlewares.
	g.Use(gin.Recovery())
	g.Use(mw...)

	// 404 Handler.
	g.NoRoute(func(c *gin.Context) {
		c.String(http.StatusNotFound, "404 Page: The API route is not correct.")
	})

	// swagger在线API文档
	// 关闭swagger的方法: 启动server之前, export SWAGGER=off
	swaggerENVName := viper.GetString("swagger_env")
	g.GET("/swagger/*any",
		ginSwagger.DisablingWrapHandler(swaggerFiles.Handler, swaggerENVName))

    ...

写文档注释

main函数写文档注释: main.go

// @title IDC带宽计费管理系统 API
// @version 1.0
// @description  ### 项目功能:
// @description - 查询单月内单个机房的任意时间段的时序带宽数据和计费值, 用于绘图和表格展示;
// @description - 计算单月内任意已发生时间段的所有机房的计费值, 用于为带宽合理调度提供参考;
// @description - 提供单个机房在指定时间段的原始时序带宽打点数据的excel文件下载;
// @description - 提供单个机房的基础计费信息和历史所有计费值记录的查询;
// @description - 每月1日凌晨自动计算上月的所有机房的计费值并写入MySQL, 用于预提数据、对账、历史账单查询等;
// @description - 机房基础计费信息的增查改删, 用于维护机房基础信息.

// @contact.name API维护者
// @contact.url http://www.swagger.io/support
// @contact.email i@sre.im

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host idcbill.sre.im:8080
// @BasePath /v1/idc-bandwidth-bill
func main() {

    ...

为其他API方法写文档注释:

// @Summary 更新IDC
// @Description 用于更新一条已有IDC基础计费信息, 只更新变化字段.
// @Tags idcs
// @Accept  json
// @Produce  json
// @Param   id path uint true "2"
// @Param   idccode query string false "shxx"
// @Param   idcname query string false "上海XXX电信"
// @Param   daikuan query string false "100"
// @Param   baodi query string false "50"
// @Param   billmethod query string false "95"
// @Success 200 {string} string
// @Router /idcs/{id} [put]
func UpdateIDC(c *gin.Context) {
    ...

Param的类型有:

query
path
header
body
formData

Param的数据类型有:

string (string)
integer (int, uint, uint32, uint64)
number (float32)
boolean (bool)
user defined struct

生成文档注释

在项目根目录下执行:

swag init

会自动生成如下目录和文件:

docs/
├── docs.go
├── swagger.json
└── swagger.yaml

每次文档有更新, 都需要重新执行一次:

swag init

访问swagger在线API文档

编译项目并运行后, 访问:

http://localhost:8080/swagger/index.html

官方文档

https://github.com/swaggo/swag/blob/master/README.md

https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html