go gin集成swagger接口文档

环境
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