Beego＋Swagger 快速上手
每天讀一篇一線開發者原創好文
大綱
Beego 是什麼
為什麼寫這個
如何指導
前幾天我寫了一個《Swagger 上手指南》，覺得還是讓使用者難以上手。儘管它是一款優秀的API 工具。
但我在編寫API 的過程中發現幾個問題：
好，基於上面三點。我進行了探索：
我一直很喜歡JetBrains 旗下的開發工具，樣樣皆上精品。各種主流的編程語言都有對應的集成開發環境，即使是只使用其中的一款，插件豐富，也能實現其他編程語言的編程。
Settings —> Plugins —> Swagger Plugins Swagger Codegen
下載上述兩個插件，即可在本地編寫yaml 格式的Swagger配置文件，左邊配置，右邊可視化。
這樣可以本地實現配置文件的編寫，實現API 的編寫。
beego 是一個快速開發 Go 應用的 HTTP 框架，他可以用來快速開發 API、Web 及後端服務等各種應用，是一個 RESTful 的框架，主要設計靈感來源於 tornado、sinatra 和 flask 這三個框架，但是結合了 Go 本身的一些特性（interface、struct 嵌入等）而設計的一個框架。
其中一個功能是自動化文檔，讓用戶快速的編寫API。
即：可以編程實現API。
下面的文章即是：如何實現使用Beego + Swagger 快速開發API.
接著上回的文章Swagger 上手指南 , 我在文章多次提出Http 請求包含哪些知識？
即：根據不同的 Http 動作，訪問URL 路徑，定位資源，服務端根據請求，將資源進行返回給用戶的這麼一個過程。
Beego 採用典型的MVC框架：即M(models)、V(views)和C(controllers)
一個典型的Beego 框架的目錄大概是這樣的：
使用Beego + Swagger 編寫API 的過程中，我們只需關注這些文件：
go get github.com/astaxie/beego
go get github.com/beego/bee
beego 即：beego 庫文件，不懂環境配置搜索： Go 環境搭建
bee 即： 命令行工具，這個很好理解，go 也有命令行工具，這些都是方便創建和管理相關項目的命令行(最近也在工作中開發一個命令行工具，有時間聊聊)
開始
bee api apiTest
在 src (go項目環境變數下) 新建了一個apiTest 文件夾，裡面默認存在一些默認的API 文件
bee run -gendoc=true -downdoc=true
生成的 API 文件目錄大概這樣：
主要處理：models 、contorlers 和 routers 三個文件。
核心思路：關注這三點：http 動作、請求、以及返迴響應；無需關注具體的處理邏輯，一律使用 Fake 數據
示例：
實現下面這個例子：
例子：
前面我們已經知道了，結合Beego 和 Swagger 編寫API 的重點是在編寫 models 和 controllers： models 編寫參數、響應 即：定義各種各種的結構體和編寫具體的函數
controllers 編寫具體的http 動作請求和響應 即：定義具體的參數類型和響應值和類型等。
現在我們就以上例中的 get 方法講述如何編寫models 和 controller 。
request: 無
response: 分兩種：成功和失敗，響應值和狀態碼
則：models 層這樣編寫：
則 controller 層：
回到 Swagger 上手指南， 我們指出：全文分三個部分，一個是全局基本信息：比如Swagger 版本，介紹，BasePath 等； 核心是path 部分：一個是URL 路徑，一個是Parameters 一個是Response .
Beego + Swagger 如何實現這些信息的呢？
Beego 靠編寫注釋來實現這些信息：
router.go 文件信息注釋來實現全局信息：
填寫關鍵字後面的內容即可改變全局信息。
controller 文件內的注釋來實現path 中的Parameters 和 Response 等
上例中的controller 這樣寫：
其餘類似：
要是看不懂，正確的做法應該是：
總結
本文講述使用Beego + bee + Swagger 實現的API 的編寫。
核心在於理解：
最後效果：
ChangeLog
2018.02.08 成文
TAG:中興開發者社區 |