Golang使用Swag搭建api文档的全过程
1. 简介
Gin是Golang目前最为常用的Web框架之一。
公司项目验收需要API接口设计说明书（Golang后端服务基于Gin框架编写），编写任务自然就落到了我们研发人员身上。
项目经理提供了文档模板，让我们参考模板来手动编写，要求两天内完成，时间紧任务重。
看了下文档中API接口设计内容，很简单，但是接口数量太多还需要调整文档格式，手动编写两天肯定搞不定。
发现API接口设计内容和swagger文档格式很相近，那能不能使用工具生成swagger文档后再转换为word格式呢？
和项目经理沟通了我的想法，项目经理回答说，内容丰富、格式统一就行，不要求完全参考模板中的格式来。
既然这样，那就开干吧！
2. 生成swagger.json文档
本章节仅为演示操作步骤，编写得很简洁。
2.1. 安装swag
首先需要安装swag命令行工具：go install github.com/swaggo/swag/cmd/swag@latest。
2.2. 新建示例项目
比如新建swagdoc项目：go mod init swagedoc。
2.3. 新建main.go文件并输入示例代码
package main
import (
"net/http"
"swagdoc/docs"
"github.com/gin-gonic/gin"
swaggerfiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)
// @BasePath /api/v1
// PingExample godoc
// @Summary ping example
// @Schemes
// @Description do ping
// @Tags example
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /example/helloworld [get]
func Helloworld(g *gin.Context) {
g.JSON(http.StatusOK, "helloworld")
}
func main() {
r := gin.Default()
docs.SwaggerInfo.BasePath = "/api/v1"
v1 := r.Group("/api/v1")
{
eg := v1.Group("/example")
{
eg.GET("/helloworld", Helloworld)
}
}
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
r.Run(":8080")
}
2.4. 生成swagger.json文档
执行命令swagger init命令生成swagger.json文档。文件目录结构如下图所示：
2.5. 访问api文档
执行下列命令运行示例程序：
go mod tidy go run ./main.go
在浏览器中访问api文档 ：
可以通过浏览器直接访问api：
3. 常见问题
3.1. Error parsing type definition报错如何解决？
若出现解析类型定义的错误，需要在执行swage init时加上对应的选项：
例如：swag init --parseDependency --parseInternal
3.2. 如何编写api注释？
参考 声明式注释格式。
4. 将swagger.json文档转换为word文档
可以使用 swagger转word文档在线工具 来进行转换。
如果在线工具不能使用，可以自行参考网上教程在本地搭建转换工具来进行转换，就不在此赘述了。
转换后的word文档效果图如下所示：
5. 参考资料
以上就是Golang使用Swag搭建api文档的全过程的详细内容，更多关于Golang Swag搭建api文档的资料请关注脚本之家其它相关文章！
相关文章
这篇文章主要介绍了golang实现通过smtp发送电子邮件的方法,实例分析了Go语言基于SMTP协议发送邮件的相关技巧,需要的朋友可以参考下2016-07-07
redis 是一个内存数据库,如果你把进程杀掉,那么里面存储的数据都会消失,那么这篇文章就是来解决 redis 持久化的问题,本文给大家介绍了使用go语言实现Redis持久化,需要的朋友可以参考下2024-07-07
Go在不同类型的变量之间赋值时需要显示转换，不能自动转换。这篇文章主要和大家介绍了Go语言中基本数据类型的相互转换，感兴趣的小伙伴可以了解一下2022-10-10
在Go语言中,文件监控通常涉及到文件系统事件的监听,文件或目录的状态发生变化（如创建、删除、修改等）时,你的程序需要得到通知,所以本文给大家介绍了如何使用Go语言进行文件监控和通知,需要的朋友可以参考下2024-06-06
这篇文章主要为大家介绍了Air实现Go程序实时热重载使用过程解析示例，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步早日升职加薪2022-04-04
这篇文章主要为大家介绍了GO如何模拟流操作实现示例探究,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪2024-01-01
这篇文章主要给大家介绍了关于如何通过7分钟读懂Go的临时对象池pool以及其应用场景的相关资料，文中通过示例代码介绍的非常详细，对大家学习或使用Go具有一定的参考学习价值，需要的朋友们下面来一起看看吧2018-11-11
Go语言的errors包提供了基础的错误处理能力,允许通过errors.New创建自定义error对象,error在Go中是一个接口,通过实现Error方法来定义错误文本,对错误的比较通常基于对象地址,而非文本内容,因此即使两个错误文本相同2024-10-10
这篇文章主要介绍了用gin开发的golang项目三种开发模式方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教2024-01-01
这篇文章主要介绍了gtoken替换jwt实现sso登录,主要介绍了替换jwt的原因分析及gtoken的优势，本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下2022-05-05
最新评论