Gin实践连载八为它加上Swagger

一个好的 API's，必然离不开一个好的API文档

要开发纯手写 API 文档，不存在的 :=)

原文地址：为它加上Swagger
项目地址：https://github.com/EDDYCJY/go...

安装 swag

1、go get

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

若 $GOPATH/bin 没有加入$PATH中，你需要执行将其可执行文件移动到$GOBIN下

mv $GOPATH/bin/swag /usr/local/go/bin

2、gopm get

该包有引用golang.org上的包，若无科学上网，你可以使用 gopm 进行安装

gopm get -g -v github.com/swaggo/swag/cmd/swag

cd $GOPATH/src/github.com/swaggo/swag/cmd/swag

go install

同理将其可执行文件移动到$GOBIN下

验证是否安装成功

$ swag -v
swag version v1.1.1

安装 gin-swagger

$ go get -u github.com/swaggo/gin-swagger

$ go get -u github.com/swaggo/gin-swagger/swaggerFiles

注：三个包都有一定大小，安装需要等一会或要科学上网

初始化

编写API注释

Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件

gin-swagger 给出的范例：

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string    "ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

我们可以参照 Swagger 的注解规范和范例去编写

// @Summary 新增文章标签
// @Produce  json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddTag(c *gin.Context) {

// @Summary 修改文章标签
// @Produce  json
// @Param id path int true "ID"
// @Param name query string true "ID"
// @Param state query int false "State"
// @Param modified_by query string true "ModifiedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags/{id} [put]
func EditTag(c *gin.Context) {

参考的注解请参见 go-gin-example。以确保获取最新的 swag 语法

生成

我们进入到gin-blog的项目根目录中，执行初始化命令

[$ gin-blog]# swag init
2018/03/13 23:32:10 Generate swagger docs....
2018/03/13 23:32:10 Generate general API Info
2018/03/13 23:32:10 create docs.go at  docs/docs.go

完毕后会在项目根目录下生成docs

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

我们可以检查 docs.go 文件中的 doc 变量，详细记载中我们文件中所编写的注解和说明

验证

大功告成，访问一下 http://127.0.0.1:8000/swagger/index.html，查看 API 文档生成是否正确

参考

本系列示例代码

go-gin-example

本系列目录

连载一 Golang介绍与环境安装
连载二搭建Blog API's（一）
连载三搭建Blog API's（二）
连载四搭建Blog API's（三）
连载五使用JWT进行身份校验
连载六编写一个简单的文件日志
连载七 Golang优雅重启HTTP服务
连载八为它加上Swagger
连载九将Golang应用部署到Docker
连载十定制 GORM Callbacks
连载十一 Cron定时任务
连载十二优化配置结构及实现图片上传
连载十三优化你的应用结构和实现Redis缓存
连载十四实现导出、导入 Excel
连载十五生成二维码、合并海报
连载十六在图片上绘制文字
连载十七用 Nginx 部署 Go 应用
番外 Golang交叉编译
番外请入门 Makefile

Gin实践 连载八 为它加上Swagger