go get -u github.com/swaggo/swag/cmd/swag
// @title swagger使用例子
// @version 1.0
// @description swagger 入门使用例子
func main(){
r := gin.Default()
r.GET("/check", connectCheck)
...
}
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)
}
// 根目录执行
swag init
import (
...
_ "go-server/docs" // 这里需要引入本地已生成文档
ginSwagger "github.com/swaggo/gin-swagger"
swaggerFiles "github.com/swaggo/files"
)
func main(){
...
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run(":8080")
}
go run main.go
// 当前文档路径: localhost:swagger/index.html
参数名称
参数类型
数据类型
是否必须
备注
限制属性
] 空格分割
@Params userId query string true "用户id" minlength(3) maxlength(100) @Params status query integer false "状态:0 1" Enums(0, 1) defualt(0)
状态码
{数据类型}
数据类型
备注
]
@Success 200 {object} Response "返回空对象"
状态码
{数据类型}
数据类型
备注
]
@Failure 400 {object} ResponseError
状态码
{数据类型}
数据类型
备注
]
// @Header 200 {string} Token "qwerty"
type User struct{
ID int `json:"id" example:"232323"`
Name string `json:"name" example:"Coco" `
}