# 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/
