golang 使用Beego + Swagger構建更好的API服務

API代碼與文檔同步

   從go的代碼注釋到產生swagger.json服務說明文檔，使用了beego架構的功能，其parse了代碼特定格式的注釋，產生了符合swargerV2.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 ming.zhao@hobot.cc// @TermsOfServiceUrl http://www.horizon.ai/// @License Apache 2.0// @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html

   在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() {...}

   對應產生的內容

   在修改代碼的同時，只要順手保證注釋同步更新，並使用 bee run -downdoc=true -gendoc=true 就可以得到最新的API說明文檔並可以手動“try it out”。

Swagger 和 OpenApi 規範

   我們現在使用的主要是V2的版本，其規範細節如連結。一個更好理解的可視化版本如下圖，組成的最主要的部分已經全部給出：

    Swagger項目本身的初衷是給出一個能力：只需要編寫約定好的規範的服務說明文檔，就可以分別產生服務端和用戶端代碼，特別適合產品快速的原型搭建。swagger.json可以手寫，也可以使用專門的編輯器。

   閱讀完這個教程，你就可以比較熟練的編寫規範的說明文檔。

    writing-openapi-swagger-specification-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-codegenAvailable 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代碼