Golang使用Swag搭建api文档

1. 简介

Gin是Golang目前最为常用的Web框架之一。

公司项目验收需要API接口设计说明书(Golang后端服务基于Gin框架编写),编写任务自然就落到了我们研发人员身上。

项目经理提供了文档模板,让我们参考模板来手动编写,要求两天内完成,时间紧任务重。

看了下文档中API接口设计内容,很简单,但是接口数量太多还需要调整文档格式,手动编写两天肯定搞不定。

发现API接口设计内容和swagger文档格式很相近,那能不能使用工具生成swagger文档后再转换为word格式呢?

和项目经理沟通了我的想法,项目经理回答说,内容丰富、格式统一就行,不要求完全参考模板中的格式来。

既然这样,那就开干吧!

2. 生成swagger.json文档

本章节仅为演示操作步骤,编写得很简洁。如果需要进一步的了解请查阅【[4. 参考资料](#4. 参考资料)】章节

2.1. 安装swag

首先需要安装swag命令行工具:go install github.com/swaggo/swag/cmd/swag@latest。

2.2. 新建示例项目

比如新建swagdoc项目:go mod init swagedoc。

2.3. 新建main.go文件并输入示例代码

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文档

执行下列命令运行示例程序:

shell 复制代码
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. 参考资料

如何使用Swag将Go的注释转换为Swagger文档?

源码示例

相关推荐
程序员Query2 天前
day01-认识Go语言 + golang环境的安装
开发语言·后端·golang
喵了几个咪3 天前
GoWind Flow 拆解:一个 Go 工作流引擎与它的双模式设计器
开发语言·人工智能·后端·golang
codeejun3 天前
每日一Go·MySQL-14、慢 SQL 产生原因全解
sql·mysql·golang
利威尔xu6 天前
Go map 底层崩溃:3 个 goroutine 并发写同一张 map,fatal error 崩掉整个服务
golang·源码·map·并发·后端开发
利威尔xu7 天前
2026-11-08-Go-defer-panic-recover面试
面试·golang
JWASX8 天前
【Go】map 源码解析 - group
后端·golang·map·源码分析
联犀9 天前
纯 Go 的 CAD 开源库 go-cad:直接解析 DWG/DXF,现在也能导出 PDF
开发语言·golang·pdf
FungLeo9 天前
成为全栈·Go 后端篇·三轮代码审阅之后:把可读性和证据做成工程规则
golang·go·ast·静态检查·成为全栈·代码审阅
联犀9 天前
联犀 Go SIMD 实战:视频转码从 16.5ms 到 5.46ms
开发语言·golang·音视频
紧跟先前的步伐10 天前
Go AI Agent 实战 28|Agent 的预算、超时与停止条件
开发语言·人工智能·后端·ai·golang