「连载八」为它加上Swagger

  1. 涉及知识点
  2. 本文目标
  3. 安装 swag
    1. 验证是否安装成功
  4. 安装 gin-swagger
  5. 初始化
    1. 编写 API 注释
    2. 路由
    3. 生成
    4. 验证
  6. 参考
    1. 本系列示例代码
  7. 关于
    1. 修改记录
    1. 我的公众号

涉及知识点

  • Swagger

本文目标

一个好的 API's,必然离不开一个好的API文档,如果要开发纯手写 API 文档,不存在的(很难持续维护),因此我们要自动生成接口文档。

安装 swag

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

$GOROOT/bin 没有加入$PATH中,你需要执行将其可执行文件移动到$GOBIN

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

验证是否安装成功

检查 $GOBIN 下是否有 swag 文件,如下:

1
2
$ swag -v
swag version v1.1.1

安装 gin-swagger

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

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

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

初始化

编写 API 注释

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

gin-swagger 给出的范例:

1
2
3
4
5
6
7
8
9
// @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 的注解规范和范例去编写

1
2
3
4
5
6
7
8
// @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) {
1
2
3
4
5
6
7
8
9
// @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 语法

路由

在完成了注解的编写后,我们需要针对 swagger 新增初始化动作和对应的路由规则,才可以使用。打开 routers/router.go 文件,新增内容如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
package routers

import (
...

_ "github.com/EDDYCJY/go-gin-example/docs"

...
)

// InitRouter initialize routing information
func InitRouter() *gin.Engine {
...
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
...
apiv1 := r.Group("/api/v1")
apiv1.Use(jwt.JWT())
{
...
}

return r
}

生成

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

1
2
3
4
[$ 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

1
2
3
4
5
docs/
├── docs.go
└── swagger
├── swagger.json
└── swagger.yaml

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

验证

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

image

参考

本系列示例代码

关于

修改记录

  • 第一版:2018 年 02 月 16 日发布文章
  • 第二版:2019 年 10 月 01 日修改文章

如果有任何疑问或错误,欢迎在 issues 进行提问或给予修正意见,如果喜欢或对你有所帮助,欢迎 Star,对作者是一种鼓励和推进。

我的公众号

image


免责声明:本页面内容均来源于站内编辑发布,部分信息来源互联网,并不意味着本站赞同其观点或者证实其内容的真实性,如涉及版权等问题,请立即联系客服进行更改或删除,保证您的合法权益。转载请注明来源,欢迎对文章中的引用来源进行考证,欢迎指出任何有错误或不够清晰的表达。也可以邮件至 sblig@126.com

推荐阅读:

文章标题:「连载八」为它加上Swagger

本文作者:知识铺

发布时间:2018-03-18, 12:00:00

最后更新:2020-04-19, 17:52:49

原始链接:https://blog.zshipu.com/2018/03/18/golang/go/gin/2018-03-18-swagger/

版权声明: "署名-非商用-相同方式共享 4.0" 转载请保留原文链接及作者。

目录
×

喜欢就点赞,疼爱就打赏