1. 创建Beego项目
使用bee new命令创建beego-swagger项目
bee new beege-swagger
2. 开启自动生成文档
修改conf/app.conf文件,添加如下配置,开启文档自动生成
# 开启自动生成文档
EnableDocs = true
3. 生成文档
控制台输入如下命令生成文档
# 生成文档,该命令执行后,会在当前项目下生成swagger文件夹及swagger.json,swagger.yml文件
# swaager.json, swagger.yml文件包含各个url的映射信息, 可通过该文件来查看url的映射是否正确
bee generate docs
该命令执行后,会在当前项目下生成swagger目录, 该目录下包含swagger.json, swagger.yml文件
4. 下载Swagger并集成
A. 下载 beego/swagger v2 并将其解压到当前项目的swagger目录下
B. 修改index.html文件,内容如下
5. Swagger静态目录配置
修改main.go文件, 在main函数中设置beego中swagger静态文件目录
package main
import (
_ "beego-swagger/routers"
"github.com/astaxie/beego"
)
func main() {
// 设置beego中swagger的静态文件目录
if beego.DEV == "dev" {
beego.SetStaticPath("/swagger", "swagger")
}
beego.Run()
}
6. 路由及命名空间配置
修改router.go文件, 该文件用于配置各个Controller的映射信息, 修改代码如下:
// @APIVersion 1.0.0
// @Title beego Test API
// @Description beego has a very cool tools to autogenerate documents for your API
// @Contact [email protected]
// @TermsOfServiceUrl http://beego.me/
// @License Apache 2.0
// @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html
// 配置路由映射,以上注解必须添加
package routers
import (
"beego-swagger/controllers"
"github.com/astaxie/beego"
)
func init() {
ns := beego.NewNamespace("/v1",
// UserController的路由映射
beego.NSNamespace("/user",
beego.NSInclude(
&controllers.UserController{},
),
),
// 其余Controller的路由映射在这里添加...
)
beego.AddNamespace(ns)
}
7. Controller及其注解配置
Controller代码的编写, 其中Swagger的配置是通过注解来实现的
package controllers
import (
"beego-swagger/models"
"github.com/astaxie/beego"
)
type UserController struct {
beego.Controller
}
// swagger注解配置
// @Title Get
// @Description get user
// @router /get [Get]
func (userController *UserController) Get() {
user := &models.User{}
newUser := user.GetUser()
userController.Data["json"] = newUser
userController.ServeJSON()
}
user.go
package models
type User struct {
Id int
Name string
}
func (this *User) GetUser() (User) {
return User{Id:1, Name:"fly"}
}
在配置完Controller之后, 需要重新执行bee generate docs文件, 用以重新生成swagger的映射文件swagger.json, swagger.yml
8. 运行项目
运行项目, 浏览器访问http://localhost:8080/swagger/index.html, 弹出界面如下则表示配置成功