# Swagger * * * * * --: 作者:Fuzz 时间:2018年9月13日 * * * * * ## Swagger是什么？ > Swagger 是一个规范和一套完整的框架，用于生成、描述、调用以及可视化 RESTful 风格的 Web API接口文档 > Swagger 让部署管理和使用API从未如此简单。 > Swagger 让开发不用去写接口文档 ## 自动文档的好处？ > 不用手动写文档了，通过注解就可以自动化文档 > 文档和代码同步更新，代码更新之后不需要再更新文档 > 浏览器友好 > 使用Swagger框架可以调试API，在浏览器端可以看到更多的`request`和`response`信息 ### bee启动项目自动化接口文档 `在配置文件中设置：EnableDocs = true` 代表开启自动化文档  #### 启动beego 自动化文档 > bee run -gendoc=true -downdoc=true #### 命令解析 > -gendoc=true 表示每次自动化的 build 文档 > -downdoc=true 就会自动的下载 swagger 文档查看器 ## 路由设置 ### 路由组 ~~~ // @APIVersion 1.0.0 // @Title 公共模块接口 // @Description 公共模块接口平台 package routers import ( "public/controllers" "github.com/astaxie/beego" ) func init() { ns := beego.NewNamespace("/api", beego.NSNamespace("/login", beego.NSInclude( &controllers.LoginController{}, ), ), ) beego.AddNamespace(ns) } ~~~  > 在beego 动化文档只支持如下的写法的解析，其他写法函数不会自动解析，即 namespace+Include 的写法，而且只支持二级解析，一级版本号，二级分别表示应用模块 ### 控制器  #### 必须使用// 注释 // @Title 登陆 // @Description 用户登陆接口 // @Param account query string true "用户账号" // @Param password query string true "用户密码" // @Success 200 {object} models.UcUser //三个参数 状态码 数据类型 结构体位置（注意：如果结构体在当前页面需要加上当前包名称例如包名为controllers 则结构体位置为 controllers.UcUser ） // @Failure 100 账号错误或用户不存在 // @router /login [get] ### 访问接口文档地址 > http://127.0.0.1:8082/swagger/ > http://ip地址:端口:/swagger/