go gin框架集成gin-swagger生成接口文档

 

• 　　下载swag 工具

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

• 　　测试swag工具是否安装成功：

　　1、出现上面问题，首先看，是否把gopath 的bin目录设置为系统 的可执行命令，即加入系统path环境变量

　　2 检测bin目录是否生成swag.exe文件，如未生成，到swag的下载文件位置执行go install命令

 

 

• 再次执行swag -v成功后，显示成功后的版本信息

D:\code\go\src\onlincerestaurant>swag -v
swag version v1.8.8

• 执行swag  init命令后，项目根据会生成docs目录

• 下载gin-swagger相关的包

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

• 下载成功后，在main主函数，添加相关注解，并在项目启动前加入如下代码

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

// @contact.name  API Support
// @contact.url   http://www.swagger.io/support
// @contact.email support@swagger.io

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

 

• swagger接口文档，是根据控制器中，接口路由的注解配置生成的，json文件，所以配置对了才会生成文档

// @Summary    发送验证码
// @Description  get 发送验证码
// @Tags         member
// @Accept       json
// @Produce      json
// @param        phone  query string   true  "phone请求参数"
// @Success      200  {object}   object
// @Failure      500  {object}  object
// @Router       /api/sendcode [get]

　　参数param的几种类型 

query 形如 /user?userId=1
body 需要将数据放到 body 中进行请求
formData multipart/form-data* 请求
path 形如 /user/1
header header头信息

• 　　上传附件，注解配置

// @Summary    用户头像上传
// @Description    用户头像上传
// @Tags         member
// @Accept       multipart/form-data
// @Produce      json
// @param        user_id body string true "请求参数"
// @param        file_img formData   file true "file"
// @Success      200  {object}   object
// @Failure      500  {object}  object
// @Router       /api/upload_img [post]
func (mc *MemberController) uploadImg(ctx *gin.Context) {

    //1、 解析上传的参数file、user_id
    userId := ctx.PostForm("user_id")
    fmt.Sprintf("userid:" + userId)
    file, err := ctx.FormFile("file_img")
    if err != nil || userId == "" {
        tool.Failed(ctx, "参数解析失败", "")
        return
    }

 

　　

配置好后，执行swag  init命令后，注解会生生效，然后启动项目即可

 

 　　参考：https://blog.csdn.net/ling1998/article/details/124205500