一. 更好的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
在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”
更多细节内容请参考
- beego相关内容文档
- web展示和调用原理：swagger-ui
三. Swagger 和 OpenApi 规范
Swagger在发展到V2之后捐赠给了社区，作为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代码
更好的工作，更好的生活。