使用Beego+Swagger构建更好的API服务

一. 更好的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 ming.zhao@hobot.cc
// @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相关内容文档
  2. web展示和调用原理: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 代码结构

更好的工作,更好的生活。

推荐阅读更多精彩内容