API管理-定制yaml文件管理api并基于yaml文件生成client端、server端、springboot完整程序

原创
2019/07/02 23:14
阅读数 851

1. api管理方式背景

随着项目团队不断地规范,开发流程的每一步都在不断的变化,变得更加高效并且方便管理;api管理也经历了不少的变化,主要变化从上到下演进:

  • 编写后端接口api,从status的action到springmvc的@RequestMapping,这些框架的确可以帮我们完成后端接口的编写,但对于前后端分离的项目,还需要编写项目组制定的接口文档;我相信,没多少程序员写完接口后还想写接口文档的。
  • 由于项目组开发系统比较多,为了统一管理公司内部所有系统的接口文档,这个时候有的公司会定制化自己的接口文档管理应用,通过这个应用可以简单的实现在网站上直接编写接口文档信息,无须考虑接口文档样式等等,这样做的确比上一种好一点,通过对定制化这个网站,我们可以做到在线调试接口情况、分版本管理、分配api管理权限。API管理-使用开源xxl-api项目管理接口
  • 在项目中集成swagger并在接口上加上api信息的注解,并通过swagger-ui.html界面进行api接口的查看和调试,详细请参考:API管理-基于SpringBoot项目集成swagger实现接口文档自动生成,如果觉得这套ui不友好,没关系,可以换,API管理-舍弃springfox-swagger-ui,采用功能更加丰富的swagger-bootstrap-ui
  • 通过上面一种就基本可以完成api管理操作了,但这样的swagger管理起来也存在代码侵入性太高,为了达到目的还需要反复的调整接口注解或参数;既然存在问题,阅读完这篇文章你就会学会:如何定制yaml文件管理api并基于yaml文件生成client端、server端、springboot完整程序,接下来进入主题。

2. 需要了解几个概念

  • swagger 2.0和open api 3.0规范,其实就是规范对于的yaml文件格式定义,不同的情况下可以通过特定的规范进行不同后端代码生成,对于swagger 2.0和open api 3.0规范生成代码的插件也有好多个,swagger 2.0和open api 3.0还支持互转,请参考:swagger2openapi

这里先介绍基于swagger 2.0生成后端代码,试过open api 3.0去做,但插件不太给力,没有达到我想要的效果,没法达到:基于yaml文件生成client端、server端、springboot完整程序;

  • 满足swagger 2.0文件有json、yaml二种格式的,所以以后我们只要学会编写这种yaml或json文件编写规范就可以对接口进行管理。

3. 使用swagger-codegen完成基于yaml文件生成client端、server端、springboot完整程序

请先阅读,这篇文章,写的不错:spring boot项目使用swagger-codegen生成服务间调用的jar包,百度了很多帖子,就这篇文章给了我想要的效果。

通过这种方法我可以生成一个只带NameApi的接口的程序("interfaceOnly" : "true"),通过对这个程序的打包依赖到项目中,就可以完成对api管理,每次更新api接口只需要编写好yaml重新生成一下jar并依赖到项目中就行,这样还可以减少swagger相关注解的侵入性。通过这种方式只用在controller上实现对于的jar中的接口,还不需要调整service和mapper中的逻辑,service和mapper层还可以通过之前方式直接生成与数据库交互的通用接口。

除此之外swagger-codegen还可以通过"library" : "feign"生产我们想要的客户端代码(jar),这里的客户端代码就是一些封装过的工具,可以通过指定方式去和server交互,如:sso-client.jar就是负责与sso-server进行交互的。swagger-codegen功能还有很多,这里就不一一介绍了。

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部