golang gin框架安装Swagger

安装swagger

go get -v -u github.com/swaggo/swag/cmd/swag
cd $GOPATH/src/github.com/swaggo/swag/cmd/swag
go install
#将其可执行文件移动到 $GOBIN 下
swag -v

安装 gin-swagger

go get -v -u github.com/swaggo/gin-swagger
go get -v -u github.com/swaggo/gin-swagger/swaggerFiles

编写API注释

#我们可以参照 Swagger 的注解规范和范例去编写
// @Summary 新增文章标签
// @Produce json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddTag(c *gin.Context) {}

// @Summary 修改文章标签
// @Produce json
// @Param id param int true "ID"
// @Param name query string true "ID"
// @Param state query int false "State"
// @Param modified_by query string true "ModifiedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags/{id} [put]
func EditTag(c *gin.Context) {}

编写说明

服务信息

// @title swagger使用例子
// @version 1.0
// @description swagger 入门使用例子
func main(){
    r := gin.Default()
    r.GET("/check", connectCheck)
    ...
}

api信息

type Response struct{
    Code uint32 `json:"code"`
    Message uint32 `json:"message"`
    Data interface{} `json:"data"`
}

type ResponseError struct{
    Code uint32 `json:"code"`
    Message uint32 `json:"message"`
}

// @summary 服务连接校验 --> 接口简介
// @Description 服务初始连接测试 --> 接口描述
// @Accept json   --> 接收类型
// @Produce json  --> 返回类型
// Success 200 {object} Response --> 成功后返回数据结构
// Failure 400 {object} ResponseError --> 失败后返回数据结构
// Failure 404 {object} ResponseError
// Failure 500 {object} ResponseError
// @Router /check [get] --> 路由地址及请求方法
func connectCheck(c *gin.Context){
    res := Response{ Code: 1001, Message: "OK", Data: "connect success !!!"}
    c.JSON(http.StatusOK, res)
}

API 注释定义

#summary 简介
// @Summary 简介
#accept 可使用的MIME类型
// @Accept json
#produce 可生成的MIME类型，既响应返回类型
// @Produce json
// @Produce png 可设置多条
#header 请求头字段 格式: [ 状态码 {数据类型} 数据类型 备注 ]
// @Header 200 {string} Token "qwerty"
#param 参数 格式: [ 参数名称 参数类型 数据类型 是否必须 备注 限制属性 ] 空格分割
// @Params userId query string true "用户id" minlength(3) maxlength(100)
// @Params status query integer false "状态：0 1" Enums(0, 1) defualt(0) 
#success 成功响应 格式: [ 状态码 {数据类型} 数据类型 备注 ]
// @Success 200 {object} Response "返回空对象"
#failure 失败响应 格式: [ 状态码 {数据类型} 数据类型 备注 ]
// @Failure 400 {object} ResponseError
#router 路由路径
// @Router /user/{userId} [get]


#参数可用类型 [param type]
query
path
header
body
formDate
值可以是 formData、query、path、body、header，formData 表示是 post 请求的数据，query 表示带在 url 之后的参数，path 表示请求路径上得参数，例如上面例子里面的 key，body 表示是一个 raw 数据请求，header 表示带在 header 信息中得参数
#数据可用类型 [data type]
string(string)
integer(int, uint, uint32, uint64)
boolean(bool)
user defined struct
#可配置属性
defualt * 参数默认值
maximum number 最大值
mininum number 最小值
maxLength integer 最大长度
minLength integer 最小长度
enums [*] 枚举类型
format string
collectionFormat string query数组分割模式

 

生成

我们进入到 gin-blog 的项目根目录中，执行初始化命令

swag init

添加路由

在docs目录下新建route.go文件

package docs

import (
  "github.com/gin-gonic/gin"
  "github.com/swaggo/gin-swagger"
  "github.com/swaggo/gin-swagger/swaggerFiles"
)

func Routers(e *gin.Engine) {
  e.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

将路由添加到系统路由中

检查中间件

检查中间件是否进行鉴权操作，如果有的话设置跳过鉴权

将请求中的.html .js .css文件设置跳过

这里给一个我自己用的方法

重启服务查看

重启服务查看结果

http://域名:端口/swagger/index.html