一、什么是swagger？
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
二、Swagger 的优势
支持 API 自动生成同步的在线文档：
使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：
光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
三、Swagger 注解怎么写？
swagger-go注解模板
（一）参数示例
（1） 公共操作：
● 统一写在启动入口，即main()上
// @host localhost:8080
// @schemes https
// @BasePath /_live_client
// @Title Live_client_server
// @version 1.0(选填)
// @description 这是描述(选填)
（2） 具体API操作：
● 可放在任意方法上，建议放在API对应handler上
// @Tags 成员
// @Summary 获取在线成员数量
// @Router /online_user_total [post]
● --json请求体
// @Accept json
// @param price body number true "价格" minimum(0.01) maximum(100) example(0.01)
// @param mark body string true "备注，最大200字符" minLength(1) maxLength(200) example(这是备注)
// @param is_elive body int true "是否鹅直播1-是2-否" Enums(1, 2) example(1)
● --x-www-form-urlencoded请求体(默认表单，如 username=xx&passwd=xx)
// @Accept x-www-form-urlencoded
// @param price formData number true "价格" minimum(0.01) maximum(100) example(0.01)
// @param mark formData string true "备注，最大200字符" minLength(1) maxLength(200) example(这是备注)
// @param is_elive formData int true "是否鹅直播1-是2-否" Enums(1, 2) example(1)
● --query请求体(表示带在 url 之后的参数,如 /login?username=xx)
// @Accept mpfd
// @param price query number true "价格" minimum(0.01) maximum(100) example(0.01)
// @param mark query string true "备注，最大200字符" minLength(1) maxLength(200) example(这是备注)
// @param is_elive query int true "是否鹅直播1-是2-否" Enums(1, 2) example(1)
● --返回体
// @Produce json
// @Success 200 object Success_Response{} 成功后返回值
// @failure 500 object failure_Response{} 失败后返回值
（二）参数释义
（1） 公共操作：
// @host 主机名或IP地址
// @schemes 请求协议http、https
// @BasePath 基本路径
// @Title 应用程序的名称，如系统名
// @version 应用程序的版本
// @description 应用程序的描述
（2）具体API操作：
// @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.参数描述
（3）返回体结构示例：
// 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:""`
}
（4）Mime类型
| Alias | MIME 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 |
（5）参数类型
● query
● path
● header
● body
● formData
（6）数据类型
● string (string)
● integer (int, uint, uint32, uint64)
● number (float32)
● boolean (bool)
● user defined struct
（7）swaggo-官网地址+中文手册
https://github.com/swaggo/swag/blob/master/README_zh-CN.md
（三）安装部署步骤
1） 安装swaggo
go install github.com/swaggo/swag/cmd/swag@latest
检查安装是否成功
swag -v
安装swaggo
2） 根据上方swagger-go模板编写注解
3） 生成swaggo文档
swag init -dir ./cmd/ -output docs/api/ --pd true
--dir main.go文件所在目录
--output 输出目录
--pd 从依赖关系中解析文件 默认false
生成swagger.json
（注意：部分内容转载自，
Swagger-go 官网 https://github.com/swaggo/swag/blob/master/README_zh-CN.md）
网友评论