Go语言使用swagger生成接口文档的方法

 更新时间:2020-09-24 15:01:25   作者:佚名   我要评论(0)

swagger介绍
Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用,以设计、构建、记录和使用RESTful Web服务

swagger介绍

Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用,以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档,代码生成和测试用例生成。

在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率。可是编写接口文档历来都是令人头痛的,而且后续接口文档的维护也十分耗费精力。

最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新,而Swagger正是那种能帮我们解决接口文档问题的工具。

这里以gin框架为例,使用gin-swagger库以使用Swagger 2.0自动生成RESTful API文档。

gin-swagger实战

想要使用gin-swagger为你的代码自动生成接口文档,一般需要下面三个步骤:

  • 按照swagger要求给接口代码添加声明式注释,具体参照声明式注释格式。
  • 使用swag工具扫描代码自动生成API接口文档数据
  • 使用gin-swagger渲染在线接口文档页面

第一步:添加注释

在程序入口main函数上以注释的方式写下项目相关介绍信息。

package main

// @title 这里写标题
// @version 1.0
// @description 这里写描述信息
// @termsOfService http://swagger.io/terms/

// @contact.name 这里写联系人信息
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 这里写接口服务的host
// @BasePath 这里写base path
func main() {
 r := gin.New()

 // liwenzhou.com ...

 r.Run()
}

在你代码中处理请求的接口函数(通常位于controller层)按如下方式写上注释:

// GetPostListHandler2 升级版帖子列表接口
// @Summary 升级版帖子列表接口
// @Description 可按社区按时间或分数排序查询帖子列表接口
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query models.ParamPostList false "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponsePostList
// @Router /posts2 [get]
func GetPostListHandler2(c *gin.Context) {
 // GET请求参数(query string):/api/v1/posts2?page=1&size=10&order=time
 // 初始化结构体时指定初始参数
 p := &models.ParamPostList{
 Page: 1,
 Size: 10,
 Order: models.OrderTime,
 }

 if err := c.ShouldBindQuery(p); err != nil {
 zap.L().Error("GetPostListHandler2 with invalid params", zap.Error(err))
 ResponseError(c, CodeInvalidParam)
 return
 }
 data, err := logic.GetPostListNew(p)
 // 获取数据
 if err != nil {
 zap.L().Error("logic.GetPostList() failed", zap.Error(err))
 ResponseError(c, CodeServerBusy)
 return
 }
 ResponseSuccess(c, data)
 // 返回响应
}

上面注释中参数类型使用了objectmodels.ParamPostList具体定义如下:

// bluebell/models/params.go

// ParamPostList 获取帖子列表query string参数
type ParamPostList struct {
 CommunityID int64 `json:"community_id" form:"community_id"` // 可以为空
 Page int64 `json:"page" form:"page" example:"1"` // 页码
 Size int64 `json:"size" form:"size" example:"10"` // 每页数据量
 Order string `json:"order" form:"order" example:"score"` // 排序依据
}

响应数据类型也使用的object,我个人习惯在controller层专门定义一个docs_models.go文件来存储文档中使用的响应数据model。

// bluebell/controller/docs_models.go

// _ResponsePostList 帖子列表接口响应数据
type _ResponsePostList struct {
 Code ResCode   `json:"code"` // 业务响应状态码
 Message string   `json:"message"` // 提示信息
 Data []*models.ApiPostDetail `json:"data"` // 数据
}

第二步:生成接口文档数据

编写完注释后,使用以下命令安装swag工具:

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

在项目根目录执行以下命令,使用swag工具生成接口文档数据。

swag init

执行完上述命令后,如果你写的注释格式没问题,此时你的项目根目录下会多出一个docs文件夹。

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

第三步:引入gin-swagger渲染文档数据

然后在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容:

import (
 // liwenzhou.com ...

 _ "bluebell/docs" // 千万不要忘了导入把你上一步生成的docs

 gs "github.com/swaggo/gin-swagger"
 "github.com/swaggo/gin-swagger/swaggerFiles"

 "github.com/gin-gonic/gin"
)

注册swagger api相关路由

r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))

把你的项目程序运行起来,打开浏览器访问http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api文档了。

gin_swagger文档

gin-swagger同时还提供了DisablingWrapHandler函数,方便我们通过设置某些环境变量来禁用Swagger。例如:

r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))

此时如果将环境变量NAME_OF_ENV_VARIABLE设置为任意值,则/swagger/*any将返回404响应,就像未指定路由时一样。

总结

到此这篇关于Go语言使用swagger生成接口文档的文章就介绍到这了,更多相关Go使用swagger生成接口文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

您可能感兴趣的文章:
  • 浅谈django框架集成swagger以及自定义参数问题
  • Django REST Swagger实现指定api参数
  • django-rest-swagger对API接口注释的方法
  • django-rest-swagger的优化使用方法
  • django-rest-framework 自定义swagger过程详解

相关文章

  • Go语言使用swagger生成接口文档的方法

    Go语言使用swagger生成接口文档的方法

    swagger介绍 Swagger本质上是一种用于描述使用JSON表示的RESTful API的接口描述语言。Swagger与一组开源软件工具一起使用,以设计、构建、记录和使用RESTful Web服务
    2020-09-24
  • 谈谈对Golang IO读写的困惑

    谈谈对Golang IO读写的困惑

    前言 Golang的IO读写提供了很多种方式,目前本人知道的有io库、os库、ioutil库、bufio库、bytes/strings库等。 虽然库多是一件好事,意味着选择性多,但让我困惑
    2020-09-24
  • Go 实现热重启的详细介绍

    Go 实现热重启的详细介绍

    最近在优化公司框架 trpc 时发现了一个热重启相关的问题,优化之余也总结沉淀下,对 go 如何实现热重启这方面的内容做一个简单的梳理。 1.什么是热重启? 热重启(H
    2020-09-24
  • 详解Go 结构体格式化输出

    详解Go 结构体格式化输出

    在软件系统中定位问题时日志不可或缺,但是当一个系统功能繁多,需要打印的日志也多如牛毛,此时为了提高我们浏览日志的效率,便于阅读的输出格式必不可少。 打印结
    2020-09-24
  • Linux shell实现压缩多个文件代码实例

    Linux shell实现压缩多个文件代码实例

    Linux环境下写一个脚本 从键盘让用户输入几个文件,脚本能够将此几个文件归档压缩成一个文件: 1.首先介绍一下case语句格式 2.脚本如下: DEST读取的是压缩后文件的
    2020-09-24
  • 详解Go 并发

    详解Go 并发

    golang 天生语言层面支持并发, 非常棒的语言, 有时我们业务开发时, 遇到复杂场景, 需要用于并发, 将多个请求使用协程组完成并发, 当遇到嵌套循环,还存在上下文关系需
    2020-09-24
  • Bash技巧:把变量赋值为换行符(判断文件是否以换行符结尾)

    Bash技巧:把变量赋值为换行符(判断文件是否以换行符结尾)

    变量赋值为换行符 在 bash 中,如果要把变量赋值为换行符,写为 '\n' 没有效果,需要写为 $'\n'。具体举例如下: $ newline='\n' $ echo $newline \n $ newline=$
    2020-09-24
  • MacOS下本地golang环境搭建详细教程

    MacOS下本地golang环境搭建详细教程

    安装golang 使用homebrew安装golang。homebrew是MacOS 平台下的软件包管理工具,拥有安装、卸载、更新、查看、搜索等功能。开发者不需要关心依赖和文件路径。如果系
    2020-09-24
  • Linux shell传递参数实现原理及代码实例

    Linux shell传递参数实现原理及代码实例

    Shell 传递参数 我们可以在执行 Shell 脚本时,向脚本传递参数,脚本内获取参数的格式为:$n。n 代表一个数字,1 为执行脚本的第一个参数,2 为执行脚本的第二个参数
    2020-09-24
  • 浅析Go 字符串指纹

    浅析Go 字符串指纹

    写项目时,有时我们需要缓存, 缓存就会需要唯一的key. 常规是对字符串求md5指纹. 在golang里我们也可以使用, 目前可以计算一个字符串的crc32, md5, sha1的指纹. md5
    2020-09-24

最新评论