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 ,查看是否能够正常运行

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

相关推荐
hummhumm9 小时前
第 22 章 - Go语言 测试与基准测试
java·大数据·开发语言·前端·python·golang·log4j
hummhumm10 小时前
第 28 章 - Go语言 Web 开发入门
java·开发语言·前端·python·sql·golang·前端框架
YMWM_10 小时前
第一章 Go语言简介
开发语言·后端·golang
hummhumm11 小时前
第 25 章 - Golang 项目结构
java·开发语言·前端·后端·python·elasticsearch·golang
好奇的菜鸟11 小时前
Go语言中的引用类型:指针与传递机制
开发语言·后端·golang
Alive~o.012 小时前
Go语言进阶&依赖管理
开发语言·后端·golang
ifanatic17 小时前
[面试]-golang基础面试题总结
面试·职场和发展·golang
懒是一种态度17 小时前
Golang 调用 mongodb 的函数
数据库·mongodb·golang
XINGTECODE17 小时前
海盗王集成网关和商城服务端功能golang版
开发语言·后端·golang
入 梦皆星河17 小时前
在 Ubuntu/Debian 上安装 Go
ubuntu·golang·debian