swaggos 是一个golang版本的swagger文档生成器，提供了native code包装器，并且支持主流的web框架包裹器
下载安装 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 文档访问路由\n
eng := gin.Default()
eng.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
注释参数
主程序注释(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 Authorizationheader 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 Authorizationheaderstring true "Bearer 31a165baebe6dec616b1f8f3207b4273"
// @Param body bodyReleaseTemplateAdd true "JSON数据"
// @Success 200 {object} handler.ReportJSONResult
// @Router/api/v1/release/template/add [post]
func ReleaseTemplateAdd(c *gin.Context){
}
以上生成格式文档如下：