Go语言使用swagger生成接口文档
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)
// 返回响应
}
上面注释中参数类型使用了object
,models.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响应,就像未指定路由时一样。
本文首发于我的个人博客:liwenzhou.com
更多更详细的go web开发实战视频课程,欢迎点击博客右上角图片了解。
Go语言使用swagger生成接口文档的更多相关文章
- asp.net core 使用 swagger 生成接口文档
参考地址:http://www.cnblogs.com/daxnet/p/6181366.html http://www.jianshu.com/p/fa5a9b76f3ed 微软参考文档:https ...
- webapi 利用webapiHelp和swagger生成接口文档
webapi 利用webapiHelp和swagger生成接口文档.均依赖xml(需允许项目生成注释xml) webapiHelp:微软技术自带,仅含有模块.方法.请求-相应参数的注释. swagge ...
- .net core 使用 swagger 生成接口文档
微软参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs= ...
- asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文档
asp.net core中使用Swashbuckle.AspNetCore(swagger)生成接口文档 Swashbuckle.AspNetCore:swagger的asp.net core实现 项 ...
- Django使用swagger生成接口文档
参考博客:Django接入Swagger,生成Swagger接口文档-操作解析 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.总体目标是使客户端和文 ...
- 用Swagger生成接口文档
Swagger简介 在系统设计的时候,各个应用之间往往是通过接口进行交互的.因此接口的定义在整个团队中就变得尤为重要.我们可以把接口的规范用接口描述语言进行描述,然后Swagger可以根据我们定义的接 ...
- WebAPI使用Swagger生成接口文档
开发工具:VS2017 版本15.7.1 新建项目,选择空模板,下面只勾选WebAPI 配置Web.config <system.webServer> 节点改为 <system.we ...
- Spring Boot 集成 Swagger生成接口文档
目的: Swagger是什么 Swagger的优点 Swagger的使用 Swagger是什么 官网(https://swagger.io/) Swagger 是一个规范和完整的框架,用于生成.描述. ...
- spring-boot-route(五)整合Swagger生成接口文档
目前,大多数公司都采用了前后端分离的开发模式,为了解决前后端人员的沟通问题,后端人员在开发接口的时候会选择使用swagger2来生成对应的接口文档,swagger2提供了强大的页面调试功能,这样可以有 ...
随机推荐
- Java web Cookie详解(持久化+原理详解+共享问题+设置中文+发送多个Cookie)
Java web Cookie详解 啥是cookie? 查询有道词典得: web和饼干有啥关系? 这个谜底等等来为大家揭晓 会话技术 web中的会话技术类似于生活中两个人聊天,不过web中的会话指的是 ...
- c语言学习笔记之结构体存储
今天讲讲结构体存储问题 首先,结构体简单说是对不同类型的封装,一开始我们可能会想结构体在内存中的存储的大小是直接元素的和 例如 我们可能会觉得是 结构体大小=int(4个字节)+ short(2个字节 ...
- 朴素贝叶斯分类器基本代码 && n折交叉优化
自己也是刚刚入门.. 没脸把自己的代码放上去,先用别人的. 加上自己的解析,挺全面的,希望有用. import re import pandas as pd import numpy as np fr ...
- 论文结果图:matplotlib和seaborn实现
在论文中,可视化结果往往很重要,毕竟文字太抽象,需要图片向审稿人直观的展现出我们的结果.我也写了俩篇论文和一篇专利的申请,其中也有一些画图的程序,因此记录,防止以后忘了.由于篇幅原因,文章就不贴代码, ...
- Vue 事件的$event参数=事件的值
template <el-table :data="dataList"> <el-table-column label="id" prop=& ...
- Qt 信号发射部分 undefined reference to错误
在使用信号与槽很容易发生 undefined reference to 发射信号 ①继承QObject ②添加Q_OBJECT ③执行qmake ④构建 然后就可以运行啦!但是不知道是为什么,悄咪咪 ...
- Java并发---并发理论
一.如何理解线程安全 在多线程中稍微不注意就会出现线程安全问题,那么什么是线程安全问题? 我的认识是.在多线程下代码执行的结果和预期的正确的结果不一致,该代码就是线程不安全的,否则就是线程安全的 在深 ...
- K8S(11)配置中心实战-单环境交付apollo三组件
k8s配置中心实战-交付apollo三组件 目录 k8s配置中心实战-交付apollo三组件 1 apollo简单说明 1.1 apollo最简架构图: 1.2 apollo组件部署关系 2 为app ...
- char **指针动态分配地址空间
1. 定义char **类型变量,初始化为NULL 2. 分配行指针数组空间 3. 为每行分配空间 4. 释放每行的空间 5. 释放二维指针 void main() { char **pointer= ...
- go thrift demo
接口:https://gowalker.org/github.com/apache/thrift/lib/go/thrift 参考文件:https://cong.im/2018/05/14/other ...