Gin实践 连载八 为它加上Swagger

煎鱼 · · 5998 次点击 · · 开始浏览    
这是一个创建于 的文章,其中的信息可能已经有所发展或是发生改变。

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

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

安装 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 param 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) {

参考的注解可见 gin-blog

生成

我们进入到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 文档生成是否正确

参考

本系列示例代码


有疑问加站长微信联系

本文来自:Segmentfault

感谢作者:煎鱼

查看原文:Gin实践 连载八 为它加上Swagger

入群交流(和以上内容无关):加入Go大咖交流群,或添加微信:liuxiaoyan-s 备注:入群;或加QQ群:812540095

5998 次点击  
加入收藏 微博
被以下专栏收入,发现更多相似内容
1 回复  |  直到 2018-11-26 19:07:04
暂无回复
添加一条新回复 (您需要 登录 后才能回复 没有账号 ?)
  • 请尽量让自己的回复能够对别人有帮助
  • 支持 Markdown 格式, **粗体**、~~删除线~~、`单行代码`
  • 支持 @ 本站用户;支持表情(输入 : 提示),见 Emoji cheat sheet
  • 图片支持拖拽、截图粘贴等方式上传