今天项目生成swagger时,按照官方文档操作,swagger目录和压缩包都正常创建,就连http://localhost:8080/swagger/也正常访问,但是 Try it out 接口时,就 404 报错,百度说是因为commentsRouter_controllers.go(下面简称:路由文件)没有的原因。一看发现项目确实没有生成这个文件。。。。。于是耗费半天的时间才搞定,有点坑。。。。。。
1、先说项目环境:
无法生成路由文件的项目环境:
go1.16 、beegov2@v2.0.2 、bee@v2.0.2
成功生成路由文件的项目环境:
go1.16 、beegov2@v2.0.1 、bee@v2.0.1
看到这里应该就知道了,就是beego的版本造成的!!!
(具体原因还没有时间去验证,感觉是因为 go版本 和 beego版本之间的原因,如果你现在是 go1.18版本,那就可以试一试beego2.0.2、bee2.0.2和beego2.0.4、bee2.0.4)
2、beego版本解决
-
GOPATH环境变量下github.com目录中,把 beego 给删除;(不放心可以复制一份到桌面)
-
cmd,执行 go get github.com/beego/beego/v2@v2.0.1
-
下载成功在github.com目录中会重新创建 beego 目录,里面的版本就是2.0.1了
-
上github下载bee@v2.0.1版本;GitHub - beego/bee at v2.0.1
-
下载bee压缩包,放到和 beego 同级目录中
- 打开cmd,进入bee目录路径,执行 go build 进行编译
- 报错的话,是因为没有 go.sum 文件,执行 go mod tidy 即可
- 继续执行 go build 成功,会生成一个 bee.exe 程序,复制到 GOPATH 的bin目录下
- 打开cmd,执行 bee version 就可以看到当前的bee版本了
- 如果提示没有 bee 命令,就需要把 bee.exe 再复制一份到 GOROOT 下的 bin 中
3、通过上面的步骤,版本就集齐了
此时项目中go.mod用的beego版本还是v2.0.2的,那么就要改项目版本了(不懂什么原因,我在项目路径下执行 go mod tidy 时,一直默认下载 beegov2.0.2 的给我,离谱到家了)
- 将项目的 go.mod 和 go.sum 文件都删除(不放心可以复制一份到桌面)
- 执行 go mod init productmatrix,生成 go.mod 文件
- ( 或者自己创建一个文件即可,在文件go.mod中添加 replace ,如下:
module productmatrix go 1.16 // replace 指定使用依赖版本,否则执行 go mod tidy 会默认安装 v2.0.2 的给我 replace github.com/beego/beego/v2 => github.com/beego/beego/v2 v2.0.1
- 然后执行 go mod tidy 生成 go.sum 文件,查看sum文件,beego版本如下就是正确的
-
github.com/beego/beego/v2 v2.0.1 h1:07a7Z0Ok5vbqyqh+q53sDPl9LdhKh0ZDy3gbyGrhFnE= github.com/beego/beego/v2 v2.0.1/go.mod h1:8zyHi1FnWO1mZLwTn62aKRIZF/aIKvkCBB2JYs+eqQI=
- 在 app.conf 文件中将 runmode 配置为 dev ,(重要,否则 bee run 无法生成路由文件)
- 到这里执行 bee run -gendoc=true -downdoc=true 就可以了,看到 routers 目录下面终于生成路由文件了;
4、下面就是生成 swagger 文档的步骤了
- 在 app.conf 文件中添加 EnableDocs = true
appname = productmatrix httpport = 8080 runmode = "${RUNMODE||dev}" autorender = false EnableDocs = true
- 在 router.go 中创建路由规则
// @APIVersion 1.0.0 // @Title matrix API // @Description server api document // @Contact XXXX package routers import ( "productmatrix/controllers" beego "github.com/beego/beego/v2/server/web" ) func init() { ns1 := beego.NewNamespace("/v1", beego.NSNamespace("/thirdparty", beego.NSInclude( &controllers.ThirdpartyController{}, ), ), ) beego.AddNamespace(ns1) }
- 在 main.go 的 main() 方法中添加如下:( _ "productmatrix/routers" 是生成路由文件必须添加的)
package main import ( _ "productmatrix/routers" beego "github.com/beego/beego/v2/server/web" ) func main() { // 生成接口文档 if beego.BConfig.RunMode == "dev" { beego.BConfig.WebConfig.DirectoryIndex = true beego.BConfig.WebConfig.StaticDir["/swagger"] = "swagger" } beego.Run() }
- 在ThirdpartyController中定义方法和swagger注解就可以了
package controllers import ( "encoding/json" "productmatrix/errors" "productmatrix/models" beego "github.com/beego/beego/v2/server/web" "github.com/beego/beego/v2/core/logs" ) type ThirdpartyController struct { beego.Controller } // @Title getLicenseSubmitForm // @Description 许可新增接口 // @Param body body models.LicenseReq true "许可新增DTO" // @Success 200 {object} models.ResponseDTO // @Failure 500 Server Exception // @router /license/request [post] func (c *ThirdpartyController) LicenseSubmitForm() { licenseReq := models.LicenseReq{} if err := json.Unmarshal(c.Ctx.Input.RequestBody, &licenseReq); err != nil { logs.Error(err) c.ReturnError(errors.NewRuntimeError(err, "7003")) } if err := models.LicenseSubmitForms(licenseReq); err != nil { c.ReturnError(errors.NewRuntimeError(err, "7002")) } c.ReturnSuccess("license request successfully") } // @Title getLicenseSubmitFormList // @Description 许可查询接口 // @Success 200 {object} models.ResponseDTO // @Failure 500 Server Exception // @router /license/list [get] func (c *ThirdpartyController) LicenseSubmitFormList() { c.ReturnSuccess("successfully") }
- 最后,访问http://localhost:8080/swagger/就可以看到接口文档了。
欢迎大家评论和提问,一起交流学习。