swagger介绍

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用，以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档，代码生成和测试用例生成。

Swagger既满足我们输出文档的需要又能随代码的变更自动更新

这里以gin框架为例，使用gin-swagger库以使用Swagger 2.0自动生成RESTful API文档。

gin-swagger集成

想要使用gin-swagger为你的代码自动生成接口文档，一般需要下面三个步骤：

1. 按照swagger要求给接口代码添加声明式注释，具体参照声明式注释格式。
2. 使用swag工具扫描代码自动生成API接口文档数据
3. 使用gin-swagger渲染在线接口文档页面

第一步:添加注释

在接口处理函数上方,写上注释 （具体可参考声明式注释格式）

第二步:生成接口文档

编写完注释，安装以下工具

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

然后再项目根目录下执行

swag init

如果注释格式没问题，则会生成一个docs文件夹

第三步:引入gin-swagger

在项目注册路由的地方引入gin-swagger

Router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

第四步:启动项目并访问

http://localhost:8080/swagger/index.html

可以看到swagger文档了

gin-swagger同时还提供了DisablingWrapHandler函数，方便我们通过设置某些环境变量来禁用Swagger。例如：

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

此时如果将环境变量NAME_OF_ENV_VARIABLE设置为任意值，则/swagger/*any将返回404响应，就像未指定路由时一样。