使用Beego+Swagger構建更好的API服務
題圖 By NewYorker From Twitter
一. 更好的API服務
在你已經在工作中寫了很多版本，很多規範的API服務之後，你會發現，後端服務很多共性的工作需要去完成，比如：
1）良好的API說明文件，最好還附帶可訪問，試一試的服務url 2）為API提供多種語言的sdk（呼叫端程式碼：比如安卓，ios和php） 3）保證API文件和程式碼同步實時的更新（容易遺忘） 4）持續的效能profiling，優化
那麼怎樣很優雅的解決如上的問題呢？
一個比較好的方案是
beego程式碼註釋 -> swagger.json(服務說明文件) -> swagger ui(文件和聯調的web) -> swagger code generator(生成呼叫的客戶端程式碼)
二. API程式碼與文件同步
從go的程式碼註釋到生成swagger.json服務說明文件，使用了beego框架的功能，其parse了程式碼特定格式的註釋，生成了符合swaggerV2.0規範的說明文件。
routers/router.go中的註釋，對應生成的內容
// @APIVersion 1.0.0 // @Title horizon-robotics deep-learning-uni-api-server // @Description documents of server API powered by swagger, you can also generate client code by swagger. refer : https://github.com/swagger-api/swagger-codegen // @Contact [email protected] // @TermsOfServiceUrl http://www.horizon.ai/ // @License Apache 2.0 // @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html
router生成的swagger資訊
在controller中的註釋
// @Title Get 1 job's detail info // @Description Get 1 job's detail info // @Param appid body string true "your appid" // @Param appkey body string true "your appkey" // @Param job_id body string true "unique job id: eg. mobilenetres0.75_norm_1501205873" // @Success 200 {object} models.Jobinfo "ok" // @Failure 400 {object} models.RetObj "paras missing" // @Failure 500 {object} models.RetObj "do not have this job" // @router /get-job-detail [post] func (c *JobqueryController) GetDetail() {... }
對應生成的內容
controller說明
在修改程式碼的同時，只要順手保證註釋同步更新，並使用 bee run -downdoc=true -gendoc=true 就可以得到最新的API說明文件並可以手動“try it out”
更多細節內容請參考
1、beego相關內容文件: https://beego.me/docs/advantage/docs.md 2、web展示和呼叫原理：swagger-ui: https://github.com/swagger-api/swagger-ui
三. Swagger 和 OpenApi 規範
Swagger在發展到V2之後捐贈給了社群，作為OpenApi專案發展至今。
我們現在使用的主要是V2的版本，其規範細節如連結。一個更好理解的視覺化版本如下圖，組成的最主要的部分已經全部給出
swagger視覺化規範
Swagger專案本身的初衷是給出一個能力：只需要編寫約定好的規範的服務說明文件，就可以分別生成服務端和客戶端程式碼，特別適合產品快速的原型搭建。swagger.json可以手寫，也可以使用專門的編輯器
閱讀完這個教程，你就可以比較熟練的編寫規範的說明文件。 writing-openapi-swagger-specification-tutorial
tutorial
四. 生成client程式碼
呼叫API服務的客戶端sdk程式碼邏輯其實都很類似，只不過不同的語言和執行裝置需要不同的實現。另，如果API有微小的調整，多個版本的sdk還需要分別修改，這樣十分不便於維護。現在基於go code同步生成的swagger.json，可以一次生成多種語言的sdk程式碼，十分快捷方便
#!/bin/bash
#in mac, use brew install swagger-codegen.
#refer:https://github.com/swagger-api/swagger-codegen
Available languages: [akka-scala, android, apache2, apex, aspnet5, aspnetcore, async-scala, bash, csharp, clojure, cwiki, cpprest, CsharpDotNet2, dart, elixir, eiffel, erlang-server, finch, flash, python-flask, go, go-server, groovy, haskell, jmeter, jaxrs-cxf-client, jaxrs-cxf, java, inflector, jaxrs-cxf-cdi, jaxrs-spec, jaxrs, msf4j, java-play-framework, jaxrs-resteasy-eap, jaxrs-resteasy, javascript, javascript-closure-angular, java-vertx, kotlin, lumen, nancyfx, nodejs-server, objc, perl, php, php-symfony, powershell, pistache-server, python, qt5cpp, rails5, restbed, ruby, scala, scalatra, silex-PHP, sinatra, slim, spring, dynamic-html, html2, html, swagger, swagger-yaml, swift4, swift3, swift, tizen, typescript-angular2, typescript-angular, typescript-fetch, typescript-jquery, typescript-node, undertow, ze-ph]
swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l php -o ./gencode如上的一個命令 會基於http://petstore.swagger.io/v2/swagger.json 生成php呼叫的sdk程式碼
php sdk 程式碼結構
更好的工作，更好的生活。
關於作者
作者: skywalker 來源: 簡書