1安装 swag 命令
go get -u github.com/swaggo/swag/cmd/swag
2编写注解
服务基础信息（main.go)
// @title swagger使用例子
// @version 1.0
// @description swagger 入门使用例子
// @host localhost:8080 --->这里写接口服务的host
// @BasePath /api/vi -->这里写base path
api信息(controller中各个接口前)
// @summary 接口简介
// @Description 接口描述
// @Accept json --> 可生成的MIME类型，既接收类型
// @Produce json --> 可生成的MIME类型，既响应返回类型
// @Param user body domain.UserStruct "传入参数是struct"
// Success 200 {object} Response --> 成功后返回数据结构
// Failure 400 {object} ResponseError --> 失败后返回数据结构
// Failure 404 {object} ResponseError
// Failure 500 {object} ResponseError
// @Router /check [get] --> 路由地址及请求方法
API 注释定义
- param 参数 格式: [ 参数名称 参数类型 数据类型 是否必须 备注 限制属性 ] 空格分割
@Params userId query string true "用户id" minlength(3) maxlength(100)
@Params status query integer false "状态：0 1" Enums(0, 1) defualt(0)
参数可用类型 [param type]
query :表示带在 url 之后的参数 get请求
path :path 表示请求路径上得参数 /check{id} 例：@Params id path integer false
header :表示带在 header 信息中得参数
body :表示是一个 raw 数据请求 post请求
formDate:formData 表示是 post 请求的数据
数据可用类型 [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数组分割模式
- security 安全性
success 成功响应 格式: [ 状态码 {数据类型} 数据类型 备注 ]
@Success 200 {object} Response "返回空对象"
failure 失败响应 格式: [ 状态码 {数据类型} 数据类型 备注 ]
@Failure 400 {object} ResponseError
- header 请求头字段 格式: [ 状态码 {数据类型} 数据类型 备注 ]
// @Header 200 {string} Token "qwerty"
- router 路由路径
// @Router /user/{userId} [get]
3生成文档
// 根目录执行
swag init
执行后会生成docs的文件夹
./docs
├── docs.go
├── swagger.json
└── swagger.yaml
4配置文档路由
在配置路由的文件中添加
import (
_ "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")
}
5启动服务并访问
go run main.go
// 当前文档路径: localhost:swagger/index.html