go swagger生成接口文档使用教程

更新时间：2022年08月19日 11:41:54 作者：yi个俗人

这篇文章主要为大家介绍了go swagger生成接口文档使用教程示例，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪

前言

这篇文章主要介绍了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

总结

到此这篇关于go语言使用swagger生成接口文档的文章就介绍到这了, 希望可以对你的开发有一定帮助。

更多关于go swagger接口文档的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

Golang reflect反射的使用实例
Golang反射的错误大多数都来自于调用了一个不适合当前类型的方法，而且，这些错误通常是在运行时才会暴露出来，而不是在编译时，如果我们传递的类型在反射代码中没有被覆盖到那么很容易就会panic，本文就介绍一下使用go反射时很大概率会出现的错误，需要的可以参考一下
2023-04-04
详解如何使用beego orm在postgres中存储图片
这篇文章主要为大家介绍了如何使用beego orm在postgres中存储图片详解，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
2023-04-04
golang中protobuf的使用详解
protobuf是Google公司提出的一种轻便高效的结构化数据存储格式,常用于结构化数据的序列化,具有语言无关、平台无关、可扩展性特性,常用于通讯协议、服务端数据交换场景,下面我们就来看看golang中protobuf的具体使用吧
2023-10-10
基于go语言实现图片验证码的代码示例
这篇文章主要为大家详细介绍了基于go语言实现图片验证码的代码示例,文中的示例代码简洁易懂,具有一定的借鉴价值,感兴趣的小伙伴可以跟随小编一起学习一下
2023-10-10
关于golang中平行赋值浅析
这篇文章主要给大家介绍了关于golang中平行赋值的相关资料，文中通过示例代码介绍的非常详细，对大家学习或者使用golang具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
2018-08-08
Go语言之使用pprof工具查找goroutine(协程)泄漏
这篇文章主要介绍了Go语言之使用pprof工具查找goroutine(协程)泄漏,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2024-01-01
go语言实现http服务端与客户端的例子
今天小编就为大家分享一篇go语言实现http服务端与客户端的例子，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2019-08-08
GOLANG使用Context实现传值、超时和取消的方法
这篇文章主要介绍了GOLANG使用Context实现传值、超时和取消的方法，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2019-01-01
Go语言使用时会遇到的错误及解决方法详解
这篇文章主要为大家详细介绍了Go语言使用时常常会遇到的一些错误及解决方法，文中的示例代码讲解详细，感兴趣的小伙伴可以了解一下
2023-07-07
浅析golang如何在多线程中避免CPU指令重排
这篇文章主要为大家详细介绍了golang在多线程中避免CPU指令重排的相关知识,文中的示例代码讲解详细,感兴趣的小伙伴可以跟随小编一起学习一下
2024-03-03