swagger新玩法 - 让你API接口开发原地起飞

news2024/11/15 7:10:59

作为Java后台接口开发人员，无论对对接方是前端还是第三方，很多时候我们在文档和代码两头都需要费心，而做到自动的同步将会非常省心。本教程将带你领略下如何借助swagger官方提供的新玩法，让你的API接口开发原地起飞，甚至实现0对接，让你多出几倍的上班摸鱼时间来消遣或者学习新技术。

文章目录

- 你可能还在这么干
- 新解决方案的落地
- 让API接口开发原地起飞
- 初步实现
- - 生成器二次开发
  - oas定义入库
  - freemarker模板生成oas定义
  - 生成流程核心代码
- 演示开发流程如何起飞
- 后续计划
- 收徒计划

你可能还在这么干

对于一些遗留系统，为了方便从代码同步文档，开发人员在编写API接口代码时还需要加上swagger注解，以方便项目部署好后一起提供出swagger文档。当然这种做法会让你的controller比较难看，维护起来也麻烦。弊端是先有代码才有文档，而且swagger注解方式产出的文档也有环境限制，对应用本身的服务暴露也是有隐患的。

对于新项目，大伙儿也许会用APIFox这样的API管理利器，会在上面建项目，然后编辑文档，代码这一块它还没有自己成熟的生成部署方案，还是依赖于第三方的代码生成器插件，生成的代码功能定制这块还不完善，因此大部分情况下，新项目还是要自己手写API接口声明代码。

新解决方案的落地

再说新方案，首先不得不提下现在慢慢被业界所接收和公认的API接口定义规范，这也是swagger官方提出的Open API Specification，简称oas。可以从官方文档地址查阅其定义规范，最新规范已经出到3.1.0了。基于该规范有官方和第三方的swagger文档可视化插件，新版本在界面上做了些优化。说到这里，我们的想法是，既然有了API文档定义的元数据，我们是否可以自己实现插件或者web界面，做更多的用户使用体验和功能增强方面的定制呢。当然是可以的！

另外，swagger团队也基于oas规范推出了开源代码生成器项目，对各种编程语言，包括服务端API提供方以及客户端的API消费方都提供了目标代码生成的选项。因此前面提到的代码和文档自动同步的问题，用一个oas规范的定义文件就两边都搞定了。

官方Swagger编辑器地址：https://editor-next.swagger.io/，修改源文件定义后，所见即所得，可以通过node包安装方式整合到前端项目中：

在这里插入图片描述

idea的openAPI插件，也提供了这样的功能，只不过改了源文件需要重新打开：

在这里插入图片描述

另外，idea插件还提供了代码生成功能：

在这里插入图片描述

内置了OpenAPI Generator和Swagger Codegen这两款主流的生成器，前者是在后者的开发上新的分支，且维护的更好，用到人更多，而作为二次开发，本人选择的还是后者。

让API接口开发原地起飞

咱们的目标很明确，先实现服务端API接口代码的0开发，再实现客户端调用API代码的0开发，都由定制的代码生成器来生成，最后自然就实现了0对接。而这个过程中，除了对开源代码生成器插件进行二次开发外，还要对oasAPI定义文件进行很好的管理，不用开发人员来写这个文件，而是通过web端界面来对API进行查看、操作、变更历史查看、对比，以及API接口调试。再往长远计划，因为界面操作尽量做到傻瓜式，各类人员都能操作，然后完善权限、修改操作的审核流程、API包部署流程。这对开发人员来说，API接口开发只要关注业务逻辑层的实现，真的是原地起飞。

初步实现

生成器二次开发

本人二次开发用的版本包含了：

在这里插入图片描述

二次开发的目的是修复原有生成器不支持的接口生成需求，比如表单对象提交的API从独立参数列表修复成生成表单DTO对象，DTO字段以及API接口参数的泛型类型缺失等等问题；对swagger文档调试和schema展示信息缺失的漏洞修复，比如表单对象提交的查询API有swagger内容类型注解的缺失，导致无法发送请求进行调试；定制代码生成需求，比如生成Lombok注解的DTO类、生成分页接口、校验注解和自定义验证、分组验证等等支持。

这里以自定义校验为例，通过x-开头的定义项来扩展oas规范。

在这里插入图片描述

生成代码部分截图：

在这里插入图片描述

在这里插入图片描述
注意，考虑到实际API接口提供方需要给调用方提供统一的响应结构，这种要求是由各个业务系统自己定的，因此生成器不负责这块特异性的返回值类型统一包装，而是返回了后台处理的原始类型。而这部分可以交给web框架层做统一响应结构的处理。

oas定义入库

设计多张表来存储oas文件中定义的数据，将定义形式模板化，通过良好的数据库模型的设计，让用户有更好的理解。

最初版表设计：

在这里插入图片描述

初始化脚本截图：

在这里插入图片描述

这是一个查询API接口定义的例子：

在这里插入图片描述

freemarker模板生成oas定义

通过freemarker技术来基于数据库数据生成oas定义文件，交给生成器执行。

在这里插入图片描述

生成流程核心代码

这里只是完成了最初版的实现，因为生成器模块中用的日志框架和配置与本人的spring boot有冲突，日志输出有问题，待修复。

在这里插入图片描述

演示开发流程如何起飞

初步版本没有做web界面，只能走数据库dml脚本，后续接了前端界面就很方便了。用一个单元测试来一键生成代码，同时会有一个临时文件：

在这里插入图片描述

开发controller直接起飞，这里就查把controller的空实现代码生成出来了，借助于ide的生成选项页很快。controller类上只需要加一个@RestController注解，其他所有注解都在生成API接口时都做了，包含Spring MVC注解、校验注解、swagger注解、json注解等等。剩下的你只需要关注service接口调用即可。

在这里插入图片描述