go生成Swagger在线文档

核心内容：

·如何给 API 添加 Swagger 文档功能
·如何编写 API 文档

Swagger 简介：

Swagger本质上一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。
swagger通常展示信息：
1.HTTP方法（GET，POST，PUT，DELETE等）
2.URL路径
3.HTTP消息体（消息体中的参数名和类型）
4.参数位置
5.参数是否必选
6.返回的参数（参数名和类型）
7.请求和返回的媒体类型

生成swagger步骤：

第一步添加注释

声明式注释格式
Summary：简单阐述 API 的功能
Description：API 详细描述
Tags：API 所属分类
Accept：API 接收参数的格式
Produce：输出的数据格式，这里是 JSON 格式
Param：参数，分为 6 个字段，其中第 6 个字段是可选的，各字段含义为：
参数名称
参数在 HTTP 请求中的位置（body、path、query）
参数类型（string、int、bool 等）
是否必须（true、false）
参数描述
选项，这里用的是 default() 用来指定默认值
Success：成功返回数据格式，分为 4 个字段
HTTP 返回 Code
返回数据类型
返回数据模型
说明
路由格式，分为 2 个字段：
API 路径
HTTP 方法
第二步：生成接口文档数据
下载安装Gin以及Swagger依赖包
1、go get -u github.com/gin-gonic/gin
2、go get -u github.com/swaggo/swag/cmd/swag
若报以下错：
go get github.com/gin-gonic/gin: module github.com/gin-gonic/gin: Get “https://proxy.golang.org/github.com/gin-gonic/gin/@v/list”: dial tcp 172.217.160.113:443: connectex: A connection attempt failed because the connected party did not properly respond after a period of time,
or established connection failed because connected host has failed to respond.
则是国内无法访问到https://golang.org/
可替换成国内七牛云的镜像（前提是环境参数set GO111MODULE=on，不然需先执行

go env -w GO111MODULE=on）：

3、go env -w GOPROXY=https://goproxy.cn,direct

然后再下载：

4、go get -u github.com/swaggo/swag/cmd/swag

在项目根目录执行以下命令，使用swag工具生成接口文档数据。

5、

swag init

执行完上述命令后，如果你写的注释格式没问题，此时你的项目根目录下会多出一个docs文件夹。

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

第三步：引入gin-swagger渲染文档数据

然后在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容：

import (

	_ "bluebell/docs"  // 千万不要忘了导入把你上一步生成的docs

	gs "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"

	"github.com/gin-gonic/gin"
)

注册swagger api相关路由

r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

第四步：查看Swagger 2.0 Api文档

1、运行项目
2、打开浏览器访问http：(http://localhost:8080/swagger/index.html)