扫码订阅《 》或入驻星球,即可阅读文章!

GOLANG ROADMAP

阅读模式

  • 沉浸
  • 自动
  • 日常
首页
Go友会
  • 城市
  • 校园
Go学院
  • Go小课
  • Go小考
  • Go实战
  • 精品课
Go求职
  • 求职辅导🔥
  • Offer收割社群
  • 企业题库
  • 面试宝典
Go宝典
  • 在线宝典
  • B站精选
  • 推荐图书
  • 每日博文
Go仓库
实验区
  • Go周边
  • Go下载
  • Go月刊
消息
更多
  • 用户中心

    • 我的信息
    • 推广返利
  • 玩转星球

    • 星球介绍
    • 角色体系
    • 星主权益
  • 支持与服务

    • 联系星主
    • 成长记录
    • 常见问题
    • 吐槽专区
  • 合作交流

    • 渠道合作
    • 课程入驻
    • 友情链接
author-avatar

GOLANG ROADMAP


首页
Go友会
  • 城市
  • 校园
Go学院
  • Go小课
  • Go小考
  • Go实战
  • 精品课
Go求职
  • 求职辅导🔥
  • Offer收割社群
  • 企业题库
  • 面试宝典
Go宝典
  • 在线宝典
  • B站精选
  • 推荐图书
  • 每日博文
Go仓库
实验区
  • Go周边
  • Go下载
  • Go月刊
消息
更多
  • 用户中心

    • 我的信息
    • 推广返利
  • 玩转星球

    • 星球介绍
    • 角色体系
    • 星主权益
  • 支持与服务

    • 联系星主
    • 成长记录
    • 常见问题
    • 吐槽专区
  • 合作交流

    • 渠道合作
    • 课程入驻
    • 友情链接
  • 宝典简介

  • gin系列目录

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

  • 爬虫系列目录

  • gRPC系列目录

扫码订阅《 》或入驻星球,即可阅读文章!

Gin实践 连载八 为它加上Swagger


煎鱼

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

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

项目地址:https://github.com/EDDYCJY/go-gin-example

# 安装 swag

1、go get

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

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

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

2、gopm get

该包有引用golang.org上的包,若无科学上网,你可以使用 gopm (opens new window) 进行安装

gopm get -g -v github.com/swaggo/swag/cmd/swag
cd $GOPATH/src/github.com/swaggo/swag/cmd/swag
go install
1
2
3

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

# 验证是否安装成功

$ swag -v
swag version v1.1.1
1
2

# 安装 gin-swagger

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

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

# 初始化

# 编写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]
1
2
3
4
5
6
7
8
9

我们可以参照 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) {
1
2
3
4
5
6
7
8
// @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) {
1
2
3
4
5
6
7
8
9

参考的注解可见 gin-blog (opens new window)

# 生成

我们进入到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
1
2
3
4

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

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

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

# 验证

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

# 参考

# 本系列示例代码

  • go-gin-example (opens new window)
  • 安装 swag
  • 验证是否安装成功
  • 安装 gin-swagger
  • 初始化
  • 编写API注释
  • 生成
  • 验证
  • 参考
  • 本系列示例代码