环境
go version go1.15.6 darwin/amd64
测试项目
安装
go get -u github.com/swaggo/swag/cmd/swag
swag init
集成
目录结构
├── controller
│ ├── CategoryController.go
│ ├── PostController.go
│ ├── RestController.go
│ └── UserController.go
├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── ginexp
├── go.mod
├── go.sum
├── main.go
├── response
│ └── response.go
├── routes.go # 路由规则
关键配置
go.mod
module gwm.com.cn/ginexp
routes.go
import (
// 执行swag init生成的docs文件夹路径 _引包表示只执行init函数
_ "gwm.com.cn/ginexp/docs"
)
func CollectRoute(r *gin.Engine) *gin.Engine {
... ...
// import swagger 文档
swagger := r.Group("/swagger")
swagger.GET("/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
return r
}
常用项目配置
// @title 新项目
// @version 1.0
// @description 这是一个新项目
// @termsOfService http://swagger.io/terms/
// @contact.name ZhiDao Zhang
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @host 127.0.0.1:8081
// @BasePath /
func main() {
}
常用接口配置及说明
// @Summary 新增文章标签
// @version 1.0
// @Tags 文章
// @Param name body data_validation.CreateCategoryRequest true "查询参数"
// @Description 查询分类
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}" 成功
// @Failure 400 {string} json "{"code":400,"data":{},"msg":"failed"}" 失败
// @Router /categories [post]
@Summary 是对该接口的一个描述
@Tags 是对接口的标注,同一个 tag 为一组,这样方便我们整理接口
@Version 表明该接口的版本
@Accept 表示该该请求的请求类型
@Param 表示参数 分别有以下参数 参数名词 参数类型 数据类型 是否必须 注释 属性(可选参数),参数之间用空格隔开。
@Success 表示请求成功后返回,它有以下参数 请求返回状态码,参数类型,数据类型,注释
@Failure 请求失败后返回,参数同上
@Router 该函数定义了请求路由并且包含路由的请求方式。
Param 的参数类型有以下几种
query 形如 \user?username=Jack&age=18
body 需要将数据放到 body 中进行请求
path 形如 \user\1