Go-Gin-example 第五部分 加入swagger

上一节链接

swagger

为什么要用swagger

问题起源于 前后端分离

  • 后端:后端控制层,服务层,数据访问层【后端团队】
  • 前端 :前端控制层,视图层,【前端团队】
    所以产生问题:前后端联调,前端和后端人员无法做到及时协商,解决问题,导致问题爆发

什么是swagger

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

  • 号称世界上最流行的api框架
  • Restful Api文档在线自动生成工具==》api文档和api定义开发

本文目标

完成本文所搭建的gin-example项目的api文档,自动生成接口文档。

安装swag

shell 复制代码
$ go get -u github.com/swaggo/swag/cmd/swag@v1.6.5

将swag添加到全局的可执行文件夹下

shell 复制代码
mv $GOPATH/bin/swag /usr/local/go/bin

验证安装是否成功

尝试以下命令是否能够正常执行

shell 复制代码
$ swag -v

安装 gin-swagger

shell 复制代码
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

编写api注释--如何与gin集成

注释格式文档
如何与gin集成部分

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

  1. 在router.go(管理路由的文件)中引用swagger:
    针对swagger新增初始化动作和对应的路由规则

    go 复制代码
    import "github.com/swaggo/gin-swagger" // gin-swagger middleware
    import "github.com/swaggo/files" // swagger embed files
  2. router.go源代码中添加通用的api注释
    这里可以选择main.go中进行通用注释,为了方便我们从管理路由的文件进行注释
    这里由于是学习用的项目,我们这里选择简单添加标题title,版本version,以及主机名称及端号host

go 复制代码
...
// @title			gin-example
// @version		1.0
// @host			localhost:8000
func InitRouter() *gin.Engine {
	   ...
}
...
  1. 添加相关的api操作注释
    api操作的注释文档链接
    我们这里选择添加简单的介绍summary、传入的参数相关信息Param、成功的代码其返回的相关信息success、其路由地址等相关信息router
  • auth.go
go 复制代码
package api

import (
...
)
...

// @Summary 生成用户token
// @Param username query string true "username"
// @Param password query string true "password"
// @Success 200 {string} json "{"code":200."data":{},"msg":"ok"}"
// @Router /auth [get]
func GetAuth(c *gin.Context) {
...
}
  • article.go
go 复制代码
package v1

import (
...
)

// @Summary 获取单个文章
// @Produce  json
// @Param id path int true "id"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/articles [get]
func GetArticle(c *gin.Context) {
...
}

// @Summary 获取文章列表
// @Produce  json
// @Param state query int true "state"
// @Param tag_id query int true "tag_id"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/articles [get]
func GetArticles(c *gin.Context) {
...
}

// @Summary 新增文章
// @Produce  json
// @Param tagId query int true "tagId"
// @Param title query string true "title"
// @Param desc query string true "desc"
// @Param content query string true "content"
// @Param createdBy query string true "createdBy"
// @Param state query int true "state"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddArticle(c *gin.Context) {
...
}

// @Summary 修改文章
// @Produce  json
// @Param id path int true "id"
// @Param tagId query int true "tagId"
// @Param title query string true "title"
// @Param desc query string true "desc"
// @Param content query string true "content"
// @Param modifiedBy query string true "modifiedBy"
// @Param state query int false "state"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func EditArticle(c *gin.Context) {
...
}

// @Summary 删除文章
// @Produce  json
// @Param id path int true "id"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func DeleteArticle(c *gin.Context) {
...
}
  • tag.go
go 复制代码
package v1

import (
...
)

// @Summary 查询标签
// @Produce json
// @Param name query string true "name"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [get]
func GetTags(c *gin.Context) {
...
}

// @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) {
...
}

// @Summary 删除文章标签
// @Produce  json
// @Param name path int true "id"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags{id} [delete]
func DeleteTag(c *gin.Context) {
...
}

生成说明文件

进入到项目的项目根目录中,执行初始化命令

由于我们的总的通用api注释没有写在main.go中,而是在router.go中,我们使用-g标识符来告知swag,如果直接在main.go中进行api注释的话可以直接swag init

shell 复制代码
swag init -g routers/router.go

生成完毕之后会在根目录下生成docs文件夹

当前项目的目录树:

shell 复制代码
.
├── conf
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── middleware
│   └── jwt
├── models
├── pkg
│   ├── e
│   ├── logging
│   ├── setting
│   └── util
├── routers
│   └── api
│       └── v1
└── runtime
    └── logs

验证

运行并访问http://127.0.0.1:8000/swagger/index.html ,查看是否能够正常运行

之后各种操作都简单便利啦

相关推荐
tyler_download2 小时前
golang 实现比特币内核:处理椭圆曲线中的天文数字
golang·blockchain·bitcoin
疯狂的程需猿3 小时前
一个百度、必应搜索引擎图片获取下载的工具包
golang·图搜索
明月看潮生4 小时前
青少年编程与数学 02-003 Go语言网络编程 09课题、Cookie
青少年编程·golang·网络编程·编程与数学
明月看潮生5 小时前
青少年编程与数学 02-003 Go语言网络编程 15课题、Go语言URL编程
开发语言·网络·青少年编程·golang·编程与数学
明月看潮生5 小时前
青少年编程与数学 02-003 Go语言网络编程 14课题、Go语言Udp编程
青少年编程·golang·网络编程·编程与数学
hlsd#6 小时前
go 集成go-redis 缓存操作
redis·缓存·golang
RationalDysaniaer20 小时前
Gin入门笔记
笔记·gin
qq_1728055920 小时前
GIN 反向代理功能
后端·golang·go
千年死缓20 小时前
gin中间件
中间件·gin
__AtYou__20 小时前
Golang | Leetcode Golang题解之第535题TinyURL的加密与解密
leetcode·golang·题解