Go的Swagger
"接口文档在哪？" - 前端小伙伴急匆匆地问
"等我更新一下..." - 我看着改了几十次的代码，头疼地回答
是不是经常遇到这些问题：
- Word文档里的接口描述总是和实际代码不一致
- 前端说文档看不懂，经常要反复讲解参数格式
- 改完代码忘记更新文档，导致联调时出现各种问题
- 新来的同事看着厚厚的接口文档一脸茫然
- Postman里保存的测试用例和实际接口对不上
直到我遇到了Swagger...
现在：
- 代码和文档同步更新，再也不用担心文档过期
- 前端可以直接在页面上测试接口，告别繁琐的接口对接
- 新同事通过swagger页面就能快速理解接口结构
- 接口文档规范统一，团队协作效率提升
让我来分享一下Swagger是如何拯救我们的API文档的...
一、什么是Swagger
Swagger是一个帮我们自动生成API文档的工具，只要在代码里写一些简单的注释，它就能自动生成漂亮的接口文档。 它就像是一个翻译官，把我们的代码翻译成所有人都能看懂的文档。
二、为什么要用Swagger
- 不用手写文档，省时省力
- 代码和文档永远保持同步
- 可以在网页上直接测试接口
- 前端小伙伴特别容易上手
- 支持多种语言（Java、Go、Python等）
- 文档规范专业，特别适合团队协作
三、怎么用Swagger
第一步：安装工具
- 执行命令：
go install github.com/swaggo/swag/cmd/swag@latest
- 验证安装：swag -v （如果显示版本号就说明安装成功啦）
第二步：添加依赖
在go.mod中添加：
github.com/swaggo/swag
github.com/swaggo/gin-swagger
github.com/swaggo/files
第三步：在main.go中配置Swagger
import (
"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
_ "yourproject/docs" // 这里改成你的项目名
)
func main() {
r := gin.Default()
// swagger配置
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}
第四步：生成文档
- 在项目根目录执行：
init -g cmd/main.go
第五步：查看文档
四、注意事项
- 改了代码记得重新执行swag init
- 生产环境要考虑是否开放swagger页面
- 注释要写清楚，方便他人理解
五、常见问题
-
文档没更新
- 检查是否执行了swag init
- 检查注释格式是否正确
- 试试重启服务
-
访问不了swagger页面
- 检查路由配置
- 检查依赖版本
小贴士：第一次用可能会觉得写注释麻烦，但是习惯了就会发现特别好用，再也不用手动改文档啦！
常用注释标签说明：
- @Summary：接口简述
- @Description：详细描述
- @Tags：接口分类
- @Accept：接收的数据格式（如：json, xml）
- @Produce：返回的数据格式
- @Param：参数说明 格式：@Param 参数名 参数位置 参数类型 是否必须 "描述" 位置可以是：query, path, header, body, formData
- @Success：成功响应 格式：@Success 状态码 {返回类型} 返回对象
- @Failure：失败响应
- @Router：路由信息 格式：@Router 路径 [请求方法]
