步骤

1.下载swag

$ go install github.com/swaggo/swag/cmd/swag@latest

2.在接口上方写注释，这块需要提前了解下具体各字段含义

参考

// RegisterVerify godoc
// @Summary      注册验证
// @Description  RegisterVerify Description
// @Tags         注册验证
// @Accept       json
// @Produce      json
// @Param        username    query    string   true  "用户名称"  用户名
// @Param        password    query    string   true  "用户密码"  密码
// @Success      200  {object}   JSONResult{data=string}
// @Failure      400  {object}  httputil.HTTPError
// @Failure      404  {object}  httputil.HTTPError
// @Failure      500  {object}  httputil.HTTPError
// @Router       /v1/user/RegisterVerify [post]

3.运行命令swag init

命令在项目根目录下执行，swag init 后面-d 会默认在文件夹中找main.go 文件，所以如果注释不是放在main文件里面，用-g 指定具体文件

swag init -g api/v1/login/handler.go

这个命令会在当前目录下生成docs文件夹，里面三个文件，docs.go,swagger.json,swagger.yaml，里面都是页面需要展示的接口信息

4.浏览器中输入http://localhost:8080/swagger/index.html

部署过程中遇到几个问题

1.报错 internal server error doc.json

解决

把生成的docs文件import到main文件

2.外部结构无法解析报错

cannot find type definition: httputil.HTTPError

解决

命令后加

--parseDependency --parseInternal

3.内部依赖无法解析

报错

cannot find type definition: model.User

尝试解决直接把结构体放在handler文件里面能够解决问题，说明是找不到其他文件里面的结构体

但是实际项目里面考虑项目分层，需要把结构体放在一个单独model文件夹

解决

在注释的文件里面引入这个包就可以了

4.需要注释的接口在不同的包里，swag貌似没有提供可以一个命令指定多路径的功能

解决

swag init 会修改 swag.json 和swag.yaml里面的内容，而不是重置，所以如果有多个文件，把文件路径修改了执行多次即可，这里就执行了三次，四个接口

swag init -g cmd/main.go --parseDependency --parseInternal
swag init -g api/v1/login/handler.go --parseDependency --parseInternal
swag init -g api/v1/register/handler.go --parseDependency --parseInternal

5.http错误码只能写数字，无法识别变量

解决：