『Beego + Swagger 快速上手』

時間 2019-11-16

標籤 beego swagger 快速上手简体版

原文原文鏈接

大綱

Beego 是什麼
爲何寫這個
如何指導

前幾天我寫了一個Swagger 上手指南，以爲仍是讓使用者難以上手。儘管它是一款優秀的API 工具。css

但我在編寫API 的過程當中發現幾個問題：前端

編寫繁瑣：儘管會提示出關鍵字，可是不支持 yaml 自動換行，自動對齊等功能
保存不方便：儘管能夠處處yaml 或者json 格式的配置文件，但要是API 發生變動，又須要從新打開下載的包，或者在線版的Editor
不極客：Swagger 是給程序員使用的，可是單純的配置文件，程序員不太喜歡，而是喜歡那種編程實現的API，好比在本地能夠及時訪問，即便是變動也能立馬看到效果

好，基於上面三點。我進行了探索：git

第一：使用Swagger 插件

我一直很喜歡JetBrains 旗下的開發工具，樣樣皆上精品。各類主流的編程語言都有對應的集成開發環境，即便是隻使用其中的一款，插件豐富，也能實現其餘編程語言的編程。程序員

Settings --> Plugins --> Swagger Plugins || Swagger Codegengithub

下載上述兩個插件，便可在本地編寫yaml 格式的Swagger配置文件，左邊配置，右邊可視化。編程

這樣能夠本地實現配置文件的編寫，實現API 的編寫。json

第二：使用Beego 框架

beego 是一個快速開發 Go 應用的 HTTP 框架，他能夠用來快速開發 API、Web 及後端服務等各類應用，是一個 RESTful 的框架，主要設計靈感來源於 tornado、sinatra 和 flask 這三個框架，可是結合了 Go 自己的一些特性（interface、struct 嵌入等）而設計的一個框架。flask

其中一個功能是自動化文檔，讓用戶快速的編寫API。後端

即：能夠編程實現API。api

下面的文章便是：如何實現使用Beego + Swagger 快速開發API.

接着上回的文章Swagger 上手指南 , 我在文章屢次提出Http 請求包含哪些知識？

Http 動做
URL 路徑
Body 體
Response 響應

即：根據不一樣的 Http 動做，訪問URL 路徑，定位資源，服務端根據請求，將資源進行返回給用戶的這麼一個過程。

前提：理解 Beego 框架

Beego 採用典型的MVC框架：即M(models)、V(views)和C(controllers)

M 層定義數據，表及結構體等
V 層定義可視化層，即前端展示出現的頁面，這裏咱們只需下載Swagger便可使用前端文件
C 層處理業務邏輯，好比API 中的POST,PUT,GET, DELETE 等

一個典型的Beego 框架的目錄大概是這樣的：

├── conf
│   └── app.conf
├── controllers
│   ├── admin
│   └── default.go
├── main.go
├── models
│   └── models.go
├── static
│   ├── css
│   ├── ico
│   ├── img
│   └── js
└── views
    ├── admin
    └── index.tpl

複製代碼

使用Beego + Swagger 編寫API 的過程當中，咱們只需關注這些文件：

routers 定義Http URL 路徑
models 定義請求體Body 和響應 Response
controllers 處理Http 請求動做：POST、PUT、DELETE、GET等
使用的到的工具：

go get github.com/astaxie/beego

go get github.com/beego/bee

beego 即：beego 庫文件，不懂環境配置看文章 Go 語言專欄第一期

bee 即：命令行工具，這個很好理解，go 也有命令行工具，這些都是方便建立和管理相關項目的命令行(最近也在工做中開發一個命令行工具，有時間聊聊)

開始

建立API 項目

bee api apiTest

在 src (go項目環境變量下) 新建了一個apiTest 文件夾，裏面默認存在一些默認的API 文件

自動下載Swagger文件，自動化文檔，便可在本地瀏覽默認API: http://8080/swagger

bee run -gendoc=true -downdoc=true

生成的 API 文件目錄大概這樣：

├── conf
│   └── app.conf
├── controllers
│   └── object.go
│   └── user.go
├── docs
│   └── doc.go
├── main.go
├── models
│   └── object.go
│   └── user.go
├── routers
│   └── router.go
└── tests
    └── default_test.go
複製代碼

各文件做用

main.go 函數入口
models 對應的API 中涉及的body 和 response
routers 路由設置：即URL 路徑
controllers 對應URL 的動做發生和響應的處理
app.conf 配置文件

主要處理：models 、contorlers 和 routers 三個文件。

核心思路：關注這三點：http 動做、請求、以及返回響應；無需關注具體的處理邏輯，一概使用 Fake 數據

示例：

實現下面這個例子：

例子：

POST  /api/v1.0/designer/paas/{paasid}
Request
{
  "git": {
    "addr":"ssh://ipaddr/path/.git",
    "branch":"master"
  }
}

Normal response codes: 201
{
    "passid":"xxxxx",
    "local_git":"ssh://localhost/paasdata/confcenter/{paasid}/pdmng/.git"
}

Error response codes: 400
{
    "desc": "error reason"
}

GET /api/v1.0/designer/paas/{paasid}?field=detail
Request: None

Response:
201
{
    "passid":"xxxxx",
    "local_git":"ssh://localhost/paasdata/confcenter/{paasid}/pdmng/.git"
}
400
{
    "status": "no exist {paasid}"
}

PUT /api/v1.0/designer/paas/{paasid}
Request:
{
  "git": {
    "addr":"ssh://ipaddr/path/.git",
    "branch":"master"
  }
}

Normal response codes: 201
{
    "passid":"xxxxx",
    "local_git":"ssh://localhost/paasdata/confcenter/{paasid}/pdmng/.git"
}

Error response codes: 400
{
    "status": "error reason"
}

DELETE /api/v1.0/designer/paas/{paasid}
Request None

Response 201:
{
    "status": "success"
}

400:
{
    "status": "no exist the paasid"
}
複製代碼

前面咱們已經知道了，結合Beego 和 Swagger 編寫API 的重點是在編寫 models 和 controllers： models 編寫參數、響應即：定義各類各類的結構體和編寫具體的函數

controllers 編寫具體的http 動做請求和響應即：定義具體的參數類型和響應值和類型等。

如今咱們就以上例中的 get 方法講述如何編寫models 和 controller 。

GET /api/v1.0/designer/paas/{paasid}?field=detail
Request: None

Response:
201
{
    "passid":"xxxxx",
    "local_git":"ssh://localhost/paasdata/confcenter/{paasid}/pdmng/.git"
}
400
{
    "status": "no exist {paasid}"
}

複製代碼

request: 無

response: 分兩種：成功和失敗，響應值和狀態碼

則：models 層這樣編寫：

201 時的返回值信息
type PaaSIdInfoResponse struct{
    PaaSid:   string `json:"paasid"`
    LocalGit: string `json:"local_git"`
}


400 時的返回值信息

type StatusResponse struct{
    Status   string `json:"status"`
}

400 時也能夠值定義成返回一個字符串信息。但本文不這麼處理。


定義函數：表示Get 方法觸動的過程


func GetStatusResponse(paasid string) *StatusResponse {
	if paasid == "" {
		return nil
	}
	return &StatusResponse{
		Status: fmt.Sprintf("no exist %s", paasid),
	}
}

func GetSuccessResponse(paasid string) *PaaSIdInfo {
	return &PaaSIdInfo{
		PaaSid:    paasid,
		LocalInfo: fmt.Sprintf("ssh://localhost/paasdata/confcenter/%s/pdmng/.git", paasid),
	}
}

複製代碼

則 controller 層：

回到 Swagger 上手指南，咱們指出：全文分三個部分，一個是全局基本信息：好比Swagger 版本，介紹，BasePath 等；核心是path 部分：一個是URL 路徑，一個是Parameters 一個是Response .

Beego + Swagger 如何實現這些信息的呢？

Beego 靠編寫註釋來實現這些信息：

router.go 文件信息註釋來實現全局信息：

// @APIVersion 1.0.0
// @Title mobile API
// @Description mobile has every tool to get any job done, so codename for the new mobile APIs.
// @Contact astaxie@gmail.com
package routers



複製代碼

@APIVersion
@Title
@Description
@Contact
@TermsOfServiceUrl
@License
@LicenseUrl
複製代碼

填寫關鍵字後面的內容便可改變全局信息。

controller 文件內的註釋來實現path 中的Parameters 和 Response 等

// @Title getStaticBlock
// @Description get all the staticblock by key
// @Param   key     path    string  true        "The email for login"
// @Success 200 {object} models.ZDTCustomer.Customer
// @Failure 400 Invalid email supplied
// @Failure 404 User not found
// @router /staticblock/:key [get]
func (c *CMSController) StaticBlock() {

}

複製代碼

@Title 表示描述函數信息
@Description 表示較詳細介紹函數信息
@Param 表示描述API 動做中的參數：路徑中的參數，傳入的Body等
@Success 表示描述API 正確處理時的返回信息和狀態碼
@Failure 表示描述API 錯誤處理時的返回值信息和狀態碼
@router 表示API 路徑URL 
[] 表示該函數的動做類型：post、get、put、delete等
複製代碼

Beego API 文檔

上例中的controller 這樣寫：

// @Title Get
// @Description get paasid info from API
// @Param paasid path string true "The paasid name"
// @Param field query string true "field"
// @Success 201 {object} models.PaaSIdInfo
// @Failure 400 {object} models.StatusResponse
// @router /paas/:paasid [get]
func (p *PaaSController) Get() {
	paasid := p.Ctx.Input.Param(":paasid")
	if paasid != "" {
		data := models.GetSuccessResponse(paasid)
		p.Data["json"] = data
	} else {
		data := models.GetStatusResponse(paasid)
		p.Data["json"] = data
	}
	p.ServeJSON()
}
複製代碼