Gin框架系列教程（5）- 项目集成swagger及注解简单应用

Swagger介绍：

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

支持 API 自动生成同步的在线文档：
使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。提供 Web 页面在线测试 API：
光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

安装Swagger:

从 Go 1.17 开始，go get不推荐使用安装可执行文件。go install可以改用：

go install github.com/swaggo/swag/cmd/swag@latest
swag init

//是否安装成功
swag -v

项目使用：

导入

import (
    _ "gin_alingfeng/docs"


    swaggerfiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
）

主程序入口，以及swagger路由：

// @host         127.0.0.1:9000
// @schemes      http
// @Title        接口文档
// @version      v1.0
// @description  所有接口的方法，描述，参数，响应，文档，测试，仅供参考，有问题请及时联系管理员。
func main() {
	r := gin.Default()
	// 路由初始化
	routers.Routers(r)
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
	// 数据库初始化
	models.Init()
	//启动
	r.Run(":9000")
}

api方法注解：（参数，可以单独写，也可以用结构体一起放进去）

// @Summary 新增用户
// @Description 新增用户
// @Tags User
// @Accept json
// @Param name body string true "姓名" example(不超过50字)
// @Param email body string false "邮箱" example(不超过50字)
// @Param account body string true "账号" example(不超过50字)
// @Param data query modules.User true "这里是介绍"
// @Produce json
// @Success 200 {string} string "{"success":200,"msg":"新增成功"}"
// @Failure 500 {string} Add 失败后返回值
// @Router /api/v1/user/add [post]
func Add(c *gin.Context) {
	c.String(200, "user add")
}

注意：每次修改了注释都需要重新init一下：

swag init

//其他用法
 swag init -dir ./cmd/ -output docs/api/ --pd true
 --dir main.go文件所在目录
 --output 输出目录
 --pd 从依赖关系中解析文件 默认false

用法描述：

// @Tags 每个API操作的标签列表，以逗号分隔，如分组
// @Summary 该操作的简短摘要，如api名称
// @Router 以空格分隔的路径定义。 格式：path,[httpMethod]
// @Accept 请求体接收的格式，值为Mime类型
// @param 请求参数用空格分隔的参数。
    param name,param type,data type,is mandatory?,comment,attribute(optional)
    1.参数名，2.参数类型，3.参数数据类型，4.是否必须，5.参数描述，6.其他属性
    其他属性详解：
        最大最小值 minimum(0.01),maximum(100)
        最大最小长度 minLength(1),maxLength(200)
        枚举值 Enums(A, B),Enums(1, 2),Enums(1.1, 2.2)
        示例 example(A)
        默认值 default(A)-选填

// @Produce 返回体返回的格式，值为Mime类型
// @Success 以空格分隔的成功响应。
    return code,{param type},data type,comment
    1.返回状态码，2.返回参数类型，3.返回数据，4.参数描述
// @failure 以空格分隔的故障响应。
    return code,{param type},data type,comment
1. 返回状态码，2.返回参数类型，3.返回数据，4.参数描述

// Response 定义业务处理响应类型
type Success_Response struct {
    Code RespCode `json:"code" example:"0"`
    Msg  string   `json:"msg" example:"操作成功"`
    Data RespData `json:"data" example:""`
} 

// Response 定义业务处理响应类型
type failure_Response struct {
    Code RespCode `json:"code" example:"1"`
    Msg  string   `json:"msg" example:"操作失败"`
    Data RespData `json:"data  example:""`
} 

type类型：

json: application/json,
x-www-form-urlencoded: application/x-www-form-urlencoded,
xml: text/xml,
plain: text/plain,

html: text/html,

mpfd: multipart/form-data,


json-api: application/vnd.api+json,


json-stream: application/x-json-stream,


octet-stream: application/octet-stream,



png: image/png,




jpeg: image/jpeg,




gif: image/gif,

数据类型：

● string (string)
● integer (int, uint, uint32, uint64)
● number (float32)
● boolean (bool)
● user defined struct

参数类型：

● query
● path
● header
● body
● formData

最后：

访问地址：构建您的应用程序，然后访问http://localhost:8080/swagger/index.html，您将看到您的 Swagger UI。