Go gin框架 使用swagger生成API文档

swaggos 是一个golang版本的swagger文档生成器，提供了native code包装器，并且支持主流的web框架包裹器

github 地址：https://github.com/swaggo/gin-swagger

下载安装 swag

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

在Go项目根文件夹中运行Swag

在main.go所在目录执行 swag init, -g 参数是输出详细信息

执行后，会生成docs/doc.go以及docs/swagger.json,docs/swagger.yaml

$ swag init

下载gin-swagger

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

然后在路由文件引入

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

添加访问文档路由

// swage 文档访问路由

eng := gin.Default()
eng.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

注释参数

• 注释详细格式参考：https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html

• 主程序注释(main.go)

  // @title Golang Esign API
  // @version 1.0
  // @description  Golang api of demo
  // @termsOfService http://github.com
  
  // @contact.name API Support
  // @contact.url http://www.cnblogs.com
  // @contact.email ×××@qq.com
  
  //@host 127.0.0.1:8081
  func main() {
  }
  

• 控制器注释（congroller.go）

  • Get 参数方法

    type GetOperationLogListResponse struct {
        List  *[]model.OperationLog `json:"list"`
        Total int                   `json:"total"`
    }
    
    // @Title 应用中心操作日志
    // @Author mengyilingjian@outlook.com
    // @Description 获取应用中心操作日志
    // @Tags operationlog
    // @Param Authorization	header string true "Bearer 31a165baebe6dec616b1f8f3207b4273"
    // @Param route formData string false "路由"
    // @Param operator formData string false "操作者"
    // @Param operation_type formData string false "操作类型 1 新增、2 删除、3 更新"
    // @Param description formData string false "操作描述"
    // @Param start_time formData string false "开始时间"
    // @Param end_time formData string false "结束时间"
    // @Param page formData string true "页数"
    // @Param size formData string true "数据条数"
    // @Success 200 {object} GetOperationLogListResponse
    // @Router	/api/v1/app/operationlog/appcenter [get]
    func GetOperationLogList(c *gin.Context) {
        
    }
    

    以上生成文档格式如下：
    

  • Post 参数方法

    ReleaseTemplateAdd struct {
        Name               string `json:"name"`
        DeployEnv          string `json:"deploy_env"`
        GitlabType         int    `json:"gitlab_type"`
        GitlabBranchName   string `json:"gitlab_branch_name"`
        IsAutoRelease      int    `json:"is_auto_release"`
        Description        string `json:"description"`
        GitlabCITemplateID int32  `json:"gitlab_ci_template_id"`
        GitlabID           uint32 `json:"gitlab_id"`
    }
    // @Title 新增模版
    // @Author mengyilingjian@outlook.com
    // @Description 新增模版
    // @Tags release template
    // @Param Authorization	header	string true "Bearer 31a165baebe6dec616b1f8f3207b4273"
    // @Param body body	ReleaseTemplateAdd true "JSON数据"
    // @Success 200 {object} handler.ReportJSONResult
    // @Router	/api/v1/release/template/add [post]
    func ReleaseTemplateAdd(c *gin.Context){
        
    }
    

    以上生成格式文档如下：