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-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代码