一、什么是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）