Gin swagger

1、Swagger介绍

Swagger是基于标准的 OpenAPI 规范进行设计的，本质是一种用于描述使用json表示的Restful Api的接口描述语言，只要照着这套规范去编写你的注解或通过扫描代码去生成注解，就能生成统一标准的接口文档和一系列 Swagger 工具。Swagger包括自动文档，代码生成和测试用例生成。

2、安装Swagger

2.1、安装

• 1.70 之前：go get -u github.com/swaggo/swag/cmd/swag
• 1.70 之后：go install github.com/swaggo/swag/cmd/swag

需要把安装目录 暴露出来

export $PATH:$GOPATH/bin/

2.2、检测是否安装成功

$ swag -v
swag version v1.8.12
``` 


## 2.3、安装 gin-swagger 扩展

$ go get -u -v github.com/swaggo/gin-swagger
$ go get -u -v github.com/swaggo/files
$ go get -u -v github.com/alecthomas/template

# 3、使用

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

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

## 3.1、添加注释

go-swapper 注解规范说明：

注：注解详情可参见官网文档[Swagger Documentation](https://swagger.io/docs/)

| 注解      | 描述 |
|----------| --- |
| @Summary | 摘要 |
| @Produce | API 可以产生的 MIME 类型的列表，MIME 类型你可以简单的理解为响应类型，例如：json、xml、html 等等 |
| @Param   | 参数格式，从左到右分别为：参数名、入参类型、数据类型、是否必填、注释 |
| @Success | 响应成功，从左到右分别为：状态码、参数类型、数据类型、注释 |
| @Failure | 响应失败，从左到右分别为：状态码、参数类型、数据类型、注释 |
| @Router  | 路由，从左到右分别为：路由地址，HTTP 方法 |

示例demo：


```go
package main
import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
    _ "github/mwqnice/swag/docs" // 千万不要忘了导入把你上一步生成的docs
)


// URL 信息
// @Summary  获取单个文章
// @Produce  json
// @Param    id path int true "文章ID"
// @Success  200 {object} Article "成功"
// @Failure  400 {object} string "请求错误"
// @Failure  500 {object} string "内部错误"
// @Router   /api/v1/articles/{id} [get]
func (a Article) Get(c *gin.Context) {
}


// 文档信息
// 添加注释以描述信息
// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/
// @contact.name    API Support
// @contact.url     http://www.swagger.io/support
// @contact.email   support@swagger.io
// @license.name    Apache 2.0
// @license.url     http://www.apache.org/licenses/LICENSE-2.0.html
// @host            localhost:8080
// @BasePath        /api/v1
// @securityDefinitions.basic  BasicAuth
func main() { 
    r := gin.Default()    
    c := controller.NewController()
    v1 := r.Group("/api/v1")
    {
        accounts := v1.Group("/accounts")
        {
            accounts.GET(":id", c.ShowAccount)
        }    //...
}
r.Run(":8080")}
``` 


## 3.2、生成接口文档数据

*   格式化swag注解：`$ swag fmt` 

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

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

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

## 3.3、引入 gin-swagger 渲染文档数据

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

```go
import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/files"  // 这个包
    ginSwagger "github.com/swaggo/gin-swagger"  // 这个包
    _ "github/mwqnice/swag/docs" // 千万不要忘了导入把你上一步生成的docs
)
//添加swagger访问路由
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

启动项目，在浏览器中输入地址：http://127.0.0.1:8088/swagger/index.html