我要评论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文档的资料请关注代码网其它相关文章！
发表评论