go swagger生成接口文档使用教程
作者:yi个俗人 发布时间:2023-10-20 12:31:35
前言
这篇文章主要介绍了Go语言使用swagger生成接口文档的方法,希望能够对大家的学习或工作具有一定的帮助,需要的朋友可以参考下。
在前后端分离的项目开发过程中,如果后端同学能够提供一份清晰明了的接口文档,那么就能极大地提高大家的沟通效率和开发效率。那如何维护接口文档,历来都是令人头痛的,感觉很浪费精力,而且后续接口文档的维护也十分耗费精力。在很多年以前,也流行用word等工具写接口文档,这里面的问题很多,如格式不统一、后端人员消费精力大、文档的时效性也无法保障。
针对这类问题,最好是有一种方案能够既满足我们输出文档的需要又能随代码的变更自动更新,Swagger正是那种能帮我们解决接口文档问题的工具。
Swagger介绍
Swagger是基于标准的 OpenAPI 规范进行设计的,本质是一种用于描述使用json表示的Restful Api的接口描述语言,只要照着这套规范去编写你的注解或通过扫描代码去生成注解,就能生成统一标准的接口文档和一系列 Swagger 工具。Swagger包括自动文档,代码生成和测试用例生成。
1、安装
go get -u github.com/swaggo/swag/cmd/swag
在macOS中安装 swag需要执行如下命令:
mv $GOPATH/bin/swag /usr/local/go/bin
2、检测是否安装成功
$ swag -v
swag version v1.8.4
3、安装gin-swagger扩展
$ go get -u -v github.com/swaggo/gin-swagger
$ go get -u -v github.com/swaggo/files
$ go get -u -v github.com/alecthomas/template
使用
使用gin-swagger为你的代码自动生成接口文档,一般需要下面三个步骤:
按照swagger要求给接口代码添加声明式注释。
使用swag工具扫描代码自动生成api接口文档数据。
使用gin-swagger渲染在线接口文档页面。
1、添加注释
go-swapper注解规范说明:
注:注解详情可参见官网文档Swagger Documentation
注解 | 描述 |
---|---|
@Summary | 摘要 |
@Produce | API 可以产生的 MIME 类型的列表,MIME 类型你可以简单的理解为响应类型,例如:json、xml、html 等等 |
@Param | 参数格式,从左到右分别为:参数名、入参类型、数据类型、是否必填、注释 |
@Success | 响应成功,从左到右分别为:状态码、参数类型、数据类型、注释 |
@Failure | 响应失败,从左到右分别为:状态码、参数类型、数据类型、注释 |
@Router | 路由,从左到右分别为:路由地址,HTTP 方法 |
示例demo:
package main
import (
"github.com/gin-gonic/gin"
"github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "github/mwqnice/swag/docs" // 千万不要忘了导入把你上一步生成的docs
)
type Article struct{
ID uint32 `gorm:"primary_key" json:"id"`
CreatedBy string `json:"created_by"`
ModifiedBy string `json:"modified_by"`
CreatedOn uint32 `json:"created_on"`
ModifiedOn uint32 `json:"modified_on"`
DeletedOn uint32 `json:"deleted_on"`
IsDel uint8 `json:"is_del"`
Title string `json:"title"`
Desc string `json:"desc"`
Content string `json:"content"`
CoverImageUrl string `json:"cover_image_url"`
State uint8 `json:"state"`
}
func NewArticle() Article {
return Article{}
}
func main() {
r := gin.Default()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run(":8088")
}
// @Summary 获取单个文章
// @Produce json
// @Param id path int true "文章ID"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "请求错误"
// @Failure 500 {object} string "内部错误"
// @Router /api/v1/articles/{id} [get]
func (a Article) Get(c *gin.Context) {
}
// @Summary 获取多个文章
// @Produce json
// @Param name query string false "文章名称"
// @Param tag_id query int false "标签ID"
// @Param state query int false "状态"
// @Param page query int false "页码"
// @Param page_size query int false "每页数量"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "请求错误"
// @Failure 500 {object} string "内部错误"
// @Router /api/v1/articles [get]
func (a Article) List(c *gin.Context) {
return
}
// @Summary 创建文章
// @Produce json
// @Param tag_id body string true "标签ID"
// @Param title body string true "文章标题"
// @Param desc body string false "文章简述"
// @Param cover_image_url body string true "封面图片地址"
// @Param content body string true "文章内容"
// @Param created_by body int true "创建者"
// @Param state body int false "状态"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "请求错误"
// @Failure 500 {object} string "内部错误"
// @Router /api/v1/articles [post]
func (a Article) Create(c *gin.Context) {
}
// @Summary 更新文章
// @Produce json
// @Param tag_id body string false "标签ID"
// @Param title body string false "文章标题"
// @Param desc body string false "文章简述"
// @Param cover_image_url body string false "封面图片地址"
// @Param content body string false "文章内容"
// @Param modified_by body string true "修改者"
// @Success 200 {object} Article "成功"
// @Failure 400 {object} string "请求错误"
// @Failure 500 {object} string "内部错误"
// @Router /api/v1/articles/{id} [put]
func (a Article) Update(c *gin.Context) {
return
}
// @Summary 删除文章
// @Produce json
// @Param id path int true "文章ID"
// @Success 200 {string} string "成功"
// @Failure 400 {object} string "请求错误"
// @Failure 500 {object} string "内部错误"
// @Router /api/v1/articles/{id} [delete]
func (a Article) Delete(c *gin.Context) {
return
}
2、生成接口文档数据
格式化swag注解
$ swag fmt
在项目根目录执行以下命令,使用swag工具生成接口文档数据。
$ swag init
执行完上述命令后,如果你写的注释格式没问题,此时你的项目根目录下会多出一个docs文件夹。
./docs
├── docs.go
├── swagger.json
└── swagger.yaml
3、引入gin-swagger渲染文档数据
然后在项目代码中注册路由的地方按如下方式引入gin-swagger相关内容:
import (
"github.com/gin-gonic/gin"
"github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "github/mwqnice/swag/docs" // 千万不要忘了导入把你上一步生成的docs
)
//添加swagger访问路由
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
启动项目,在浏览器中输入地址:http://127.0.0.1:8088/swagger/index.html
来源:https://juejin.cn/post/7126802030944878600


猜你喜欢
- 前言前文讲述了ppi-cpi和m0-m1-m2的图形绘制,在本文中继续分享一个反映经济活动景气度的指标PMI,在本文中还是采用爬虫的方式获取
- asp无组件上传VBS编写的大家见的多了,这个是纯javascript实现的上传,原来unicode可以解决读取位置的问题,这次真的是纯JS
- 【1】MySQL中的日期时间类型MySQL中常用的几种时间类型有:date、datetime、time、year、timestamp数据类型
- 在本人看来,HTML 5是一个妥协方案,虽不激进,但更能推动技术的继续进步。没有命名空间,元素也不要求闭合(当然这并不是优点),浏览器也可以
- 问题:不同版本提交的城市文件夹数量固定,怎样确定本版本成果中缺少了哪些城市?背景:已有参照文件作为标准,利用取差集的方法#-*- codin
- 一、连接MySQL(和PHP搭配之最佳组合)格式: -h主机地址 -u用户名 -p用户密码例1:连接到本机上的MySQL。首先在打开DOS窗
- 一、写在前面从学 Python 的第一天起,我就知道了使用 pip 命令来安装包,从学习爬虫到学习 Web 开发,安装的库越来越多,从 re
- 每次访问报表都需要windows验证,这样的报表给客户确实很说不过去.SSRS 可以匿名登录的设定步骤:环境:开发工具:SQL Server
- 上一文,介绍了vue.js动态添加、删除绑定的radio选项,本文介绍如何选中radio的某一项绑定的数据和上文的model是一致的,选中r
- 搞了一个DIV+CSS菜单,兼容Firefox,分享给大家,大家一齐学习 <!DOCTYPE html PUBLIC "-/
- 在MySQL中,对于索引的使用并是一直都采用正确的决定。简单表的示例:CREATE TABLE `r2` (ID` int(11) DEFA
- 前言今天为大家介绍一个利用Python模拟登陆CSDN的案例,虽然看起来很鸡肋,有时候确会有大用处,在这里就当做是一个案例练习吧,提高自己的
- 插入排序 插入排序是这样实现的: 首先新建一个空列表,用于保存已排序的有序数列(我们称之为"有序列表")。
- 我就废话不多说了,直接上代码吧!#!/usr/bin/python3# -*- coding: utf-8 -*-import codecs
- 问题背景a=[1,4,2,1,5,6,9,0]#删除列表中的元素,其所在的位置为[1,3,7]del_index=[1,3,7]tmp=[i
- Go 在testing包中内置测试命令go test,提供了最小化但完整的测试体验。标准工具链还包括基准测试和基于代码覆盖的语句,类似于NC
- 本文实例讲述了python处理图片之PIL模块简单使用方法。分享给大家供大家参考。具体实现方法如下:#!/usr/bin/env pytho
- 环境使用Python 3.8–> 解释器 <执行python代码>Pycharm–
- 1.byte和str互转b = b"example" s = "example" bytes(s,
- 如下所示:将不想索引的文件夹设置为Excluded Folders 及设置检索不包括的文件File - Settings - -> P