网站首页 返回列表像“草根”一样，紧贴着地面，低调的存在，冬去春来，枯荣无恙。

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

2020-06-09 18:57:13 admin 1442

### 一. 更好的API服务

在你已经在工作中写了很多版本，很多规范的[API服务](https://www.jianshu.com/p/bba4239c7c03)之后，你会发现，后端服务很多共性的工作需要去完成，比如：  
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](https://link.jianshu.com?t=https://github.com/swagger-
> api/swagger-codegen)  
>  // @Contact
> [ming.zhao@hobot.cc](https://link.jianshu.com?t=mailto:ming.zhao@hobot.cc)  
>  // @TermsOfServiceUrl
> [http://www.horizon.ai/](https://link.jianshu.com?t=http://www.horizon.ai/)  
>  // @License Apache 2.0  
>  // @LicenseUrl
> [http://www.apache.org/licenses/LICENSE-2.0.html](https://link.jianshu.com?t=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://link.jianshu.com?t=https://beego.me/docs/advantage/docs.md)
  2. [web展示和调用原理：swagger-ui](https://link.jianshu.com?t=https://github.com/swagger-api/swagger-ui)

### 三. Swagger 和 OpenApi 规范

Swagger在发展到V2之后捐赠给了社区，作为OpenApi项目发展至今。  
我们现在使用的主要是V2的版本，其规范细节如[链接](https://link.jianshu.com?t=https://github.com/OAI/OpenAPI-
Specification/blob/master/versions/2.0.md)。一个更好理解的[可视化版本](https://link.jianshu.com?t=http://openapi-
specification-visual-documentation.apihandyman.io/)如下图，组成的最主要的部分已经全部给出

swagger可视化规范

Swagger项目本身的初衷是给出一个能力：只需要编写约定好的规范的服务说明文档，就可以分别生成服务端和客户端代码，特别适合产品快速的原型搭建。swagger.json可以手写，也可以使用专门的[编辑器](https://link.jianshu.com?t=https://github.com/swagger-
api/swagger-editor)

阅读完这个教程，你就可以比较熟练的编写规范的说明文档。  
[writing-openapi-swagger-specification-
tutorial](https://link.jianshu.com?t=http://apihandyman.io/writing-openapi-
swagger-specification-tutorial-part-1-introduction/)

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](https://link.jianshu.com?t=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](https://link.jianshu.com?t=http://petstore.swagger.io/v2/swagger.json)
> -l php -o ./gencode

如上的一个命令
会基于[http://petstore.swagger.io/v2/swagger.json](https://link.jianshu.com?t=http://petstore.swagger.io/v2/swagger.json)
生成php调用的sdk代码

php sdk 代码结构

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

转载文章，原文链接：使用Beego+Swagger构建更好的API服务

关键字词api BeegoSwagger

分享到：

上一篇：Go语言开发中空interface

下一篇：golang进度条

如需留言，请登录，没有账号？请注册

0 条评论 0 人参与

网站首页 返回列表像“草根”一样，紧贴着地面，低调的存在，冬去春来，枯荣无恙。

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

zhou 4年前

zhou 4年前

zhou 4年前

zhou 4年前

武云 4年前

网站首页 返回列表 像“草根”一样，紧贴着地面，低调的存在，冬去春来，枯荣无恙。

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

zhou 4年前

zhou 4年前

zhou 4年前

zhou 4年前

武云 4年前

网站首页返回列表像“草根”一样，紧贴着地面，低调的存在，冬去春来，枯荣无恙。