gin+swagger

为API提供可交互的文档页面

安装程序和安装依赖

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

通过注释描述应用

只能为顶级函数添加注释；匿名内联函数无效，如：router("/test", func(c *gin.Context){})

应用名称

为入口函数添加如下说明

// @title           测试网址 API
// @version         1.0
// @description     示例 API
// @BasePath        / 
func main(){}

无参数的GET

// @BasePath /
// @Summary 获取版本
// @Description 获取版本
// @Tags 入库APP版本
// @Produce json
// @Success 200 {object} string "{"version": "1.0.0"}"
// @Router /get-app-ver [get]

有query参数的GET

// @BasePath / 
// @Summary 设置版本
// @Description 设置版本
// @Tags 入库APP版本
// @Produce json
// @Param ver query string true "版本号，例如 1.1.2"
// @Success 200 {object} string "{"success": true}"
// @Router /set-app-ver [get]

有path参数的GET

// @BasePath /
// @Summary 开柜
// @Description 开柜
// @Tags 快递柜
// @Produce json
// @Param imei path string true "设备IMEI"
// @Param index path string true "柜门编号，从0开始"
// @Success 200 {object} string "{"success": true}"
// @Success 400 {object} string "{"success": false, "error": "设备未连接"}"
// @Router /by-imei/:imei/:index [get]

Post、multipart

// @Summary 上传并设置订单图片
// @Description 上传并设置订单图片
// @Tags 仓库操作
// @Accept multipart/form-data
// @Produce json
// @Param file formData file true "订单文件"
// @Param order_no formData string true "订单编号"
// @Success 200 {object} map[string]interface{} "{"success":true}"
// @Router /upload/order-photograph [post]

Post、JSON

声明一个结构体，作为BODY

// @BasePath /
// @Summary 转运扫描
// @Description 转运扫描
// @Tags 仓库操作-扫描相关（需登录）
// @Produce json
// @Param body body TransportScanBody true "json格式的BODY"
// @Success 200 {object} string "{"success":true}"
// @Router /api/v1/order/transport [post]

type TransportScanBody struct {
	OrderNo     string `json:"order_no"`
	TrackNo     string `json:"track_no"`
	ExpressCode string `json:"express_code"`
	ExpressName string `json:"express_name"`
}

带认证方式

入口函数的注释添加三行

// @title           集运宝Admin API
// @version         1.0
// @description     需登录的分类在网页右侧顶部有Authorize按钮，点击后输入token才能访问
// @BasePath        /

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization

需要认证的API注释增加：

// @Security ApiKeyAuth

添加后，在UI上会有一个Authorize，点击后可以填写token，发送请求自带请求头Authorization: TOKEN

其它认证方式：https://github.com/swaggo/swag/blob/master/README.md#security

生成

注释写完后（或者修改后）执行命令，生成go源码和swagger相关json、yaml

swag init

在项目中就会有一个doc目录，其中包含doc.go、swagger.json、swagger.yaml

添加访问路由：

import (
	_ "项目名/docs"  //项目名改为当前项目的包名，在go.mod中module go-back-end，go-back-end就是包名

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

router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))