基于语义分析的自动化API文档与Mock数据生成方法及系统与流程

摘要: 本发明涉及软件工程与开发工具,具体涉及基于语义分析的自动化api文档与mock数据生成方法及系统。背景技术:1、基于java/springboot框架的后端re...
基于语义分析的自动化API文档与Mock数据生成方法及系统与流程

本发明涉及软件工程与开发工具,具体涉及基于语义分析的自动化api文档与mock数据生成方法及系统。

背景技术:

1、基于java/springboot框架的后端restfulapi开发领域,api文档编写、mock数据制作以及文档与代码的同步维护是开发流程中的主要环节。目前行业普遍采用人工配合工具的实现方案:api文档主要依靠开发者在控制器、数据传输对象中手动添加swagger、openapi相关注解,再由配套组件扫描注解生成可视化文档;mock数据多通过easymock、mockjs、faker等工具按字段类型随机生成内容,或是在yapi、rap等平台逐字段手动配置示例值;当代码发生变更后,仍需人工同步更新注解与平台配置,行业内普遍缺少自动化的文档偏差检测机制。

2、现有方案存在诸多明显缺陷。其一,文档注解与业务代码深度耦合,不仅增加代码冗余噪声,还容易出现注解与实际逻辑不一致的问题,形成“幽灵注解”。其二,随机生成的mock数据脱离业务语义,姓名、手机号、金额等字段常会出现不符合实际业务形态的内容,易导致前端联调时误判边界值。其三,接口结构变更后人工更新文档易出现遗漏,造成文档与代码长期失步,持续拉高前后端沟通成本。其四,接口中使用的枚举类型仅展示原始数值,无法自动关联对应的业务含义,导致mock测试场景覆盖不完整。

3、上述问题大幅增加了开发与联调成本,因此业内亟需一套无需人工注解干预、能够语义化生成api文档与mock数据,并可自动维持文档与代码一致性的自动化解决方案。

技术实现思路

1、为此,本发明提供基于语义分析的自动化api文档与mock数据生成方法及系统,解决现有方案注解侵入业务代码,mock数据不符合业务语义,接口文档与代码易失步,枚举业务含义无法展示的问题。

2、为了实现上述目的,本发明提供如下技术方案:基于语义分析的自动化api文档与mock数据生成方法,包括:

3、s1、扫描后端服务项目的源文件,识别带有路由标注的类及其对应方法,构建接口入口表,记录接口的路径、http方法、所属类信息;

4、s2、对每个接口的请求参数类型与返回值类型进行递归解析,展开嵌套dto、泛型容器、继承链,生成字段-类型树,同步收集所述后端服务项目中枚举类的所有枚举值及其对应的tostring/注释说明;

5、s3、对所述字段-类型树中的每个叶节点,提取字段名、java数据类型、javadoc/注释文本拼接为结构化提示,并输入语言模型进行语义类别推断,输出字段对应的语义类别与置信度得分;

6、s4、将所述接口入口表、所述字段-类型树、字段语义分类结果进行合并,生成结构化的api元数据模型,所述api元数据模型包含每个字段的类型信息、语义类别、枚举映射关系、约束信息;

7、s5、基于所述api元数据模型,渲染生成符合openapi/swagger规范的api文档;同时根据所述语义类别从预置的分类数据字典中抽样生成符合业务语义的mock示例值;

8、s6、在代码保存/提交时,对比当前版本与上一版本的所述接口入口表、所述字段-类型树,识别新增接口、字段变更接口、删除接口,仅对受影响的接口重新执行s2至s5,更新对应api文档节点与mock数据。

9、作为基于语义分析的自动化api文档与mock数据生成方法优选方案,s1中,所述后端服务项目基于java/springboot框架构建,所述路由标注包括@restcontroller、@requestmapping、@getmapping、@postmapping、@putmapping、@deletemapping。

10、作为基于语义分析的自动化api文档与mock数据生成方法优选方案,s2中,所述递归解析函数公式为:

11、

12、式中,以节点为根的完整字段-类型树;为基础类型叶节点,不再递归展开;为当前节点的第k个子字段/子类型;为当前节点下子节点总数;

13、所述泛型容器包括、,所述泛型容器解析规则为:

14、泛型列表:解析规则

15、分页泛型:解析规则

16、式中,为泛型实际承载类型。

17、作为基于语义分析的自动化api文档与mock数据生成方法优选方案,s3中,所述语义类别包括姓名、手机号、邮箱、金额、时间戳、枚举引用、url;

18、当所述置信度得分低于预设阈值时,采用关键词规则库进行兜底匹配,通过字段名与关键词词典的映射关系确定字段的所述语义类别;

19、所述置信度阈值判定逻辑公式为:

20、

21、式中,为置信度判定阈值,系统预设常量,工程典型取值;为语义分类最终输出结果。

22、作为基于语义分析的自动化api文档与mock数据生成方法优选方案,s4中,识别源代码中的校验注解,提取字段的非空约束、长度约束、数值范围约束信息,并将所述约束信息写入所述api元数据模型;

23、所述非空约束逻辑模型公式为:

24、

25、所述长度约束区间模型公式为:

26、

27、式中,为字符串字段实际长度;为最小长度阈值;为最大长度阈值;

28、所述数值范围约束区间模型公式为:

29、

30、式中,为数值型字段实际取值;为数值下限;为数值上限。

31、作为基于语义分析的自动化api文档与mock数据生成方法优选方案,s5中,对于所述语义类别为枚举引用的字段,优先从s2收集的枚举值列表中随机抽取一项作为所述mock示例值,并在所述api文档和所述mock数据中同步展示该枚举值对应的业务含义说明;

32、设枚举集合为,共个枚举值,每个值抽取概率均等:

33、

34、式中,为收集的全量枚举值集合;为枚举值总个数;为第k个枚举值;为单个枚举值被选中的概率。

35、作为基于语义分析的自动化api文档与mock数据生成方法优选方案,s5中,所述分类数据字典包括真实姓名库、合法手机号段库、地址库、金额区间规则库、时间戳格式规则库、url格式规则库。

36、作为基于语义分析的自动化api文档与mock数据生成方法优选方案,s6中,通过集成ide文件保存钩子和代码版本控制系统的提交钩子,触发增量变更对比与局部更新流程。

37、作为基于语义分析的自动化api文档与mock数据生成方法优选方案,s6中,接口变更判定逻辑公式为:

38、

39、式中,为单个接口对象,为接口入口表中的独立接口单元;为代码上一版本对应的全量接口集合,由历史版本接口入口表整合而成;为代码当前版本对应的全量接口集合,由当前版本接口入口表整合而成;为上一版本中接口对应的字段-类型树;为当前版本中接口对应的字段-类型树;对所述新增接口、所述字段变更接口、所述删除接口执行s2至s5更新,无变更接口保持原有数据。

40、本发明还提供基于语义分析的自动化api文档与mock数据生成系统,采用上述的基于语义分析的自动化api文档与mock数据生成方法,包括:

41、源码扫描与入口识别单元:用于扫描后端服务项目的源文件,识别带有路由标注的类及其对应方法,构建接口入口表,记录接口的路径、http方法、所属类信息;

42、类型图谱构建单元:用于对每个接口的请求参数类型与返回值类型进行递归解析,展开嵌套dto、泛型容器、继承链,生成字段-类型树,同步收集所述后端服务项目中枚举类的所有枚举值及其对应的tostring/注释说明;

43、字段语义分类单元:用于对所述字段-类型树中的每个叶节点,提取字段名、java数据类型、javadoc/注释文本拼接为结构化提示,并输入语言模型进行语义类别推断,输出字段对应的语义类别与置信度得分;

44、api元数据模型生成单元:用于将所述接口入口表、所述字段-类型树、字段语义分类结果进行合并,生成结构化的api元数据模型,所述api元数据模型包含每个字段的类型信息、语义类别、枚举映射关系、约束信息;

45、文档渲染与mock数据生成单元:用于基于所述api元数据模型,渲染生成符合openapi/swagger规范的api文档;同时根据所述语义类别从预置的分类数据字典中抽样生成符合业务语义的mock示例值;

46、增量变更感知与局部更新单元:用于在代码保存/提交时,对比当前版本与上一版本的所述接口入口表、所述字段-类型树,识别新增接口、字段变更接口、删除接口,仅对受影响的接口重新执行s2至s5,更新对应api文档节点与mock数据。

47、本发明具有如下优点:

48、第一、本发明无需开发者在业务代码中手动编写、维护swagger、openapi等文档注解,有效避免注解侵入业务代码产生的冗余噪声与“幽灵注解”问题,大幅减少相关人工工作量,实际应用中可使源码注解行数减少约38%。

49、第二、本发明依托增量变更感知与局部更新机制,在代码保存、提交时仅对变更接口进行更新,将文档滞后周期压缩至提交触发延迟级别,从根源解决接口结构变更后文档遗漏更新、长期失步的问题,显著降低前后端因文档偏差产生的沟通频次。

50、第三、本发明借助语言模型完成字段语义分类,结合预置的各类业务数据字典生成mock数据,摒弃传统随机取值模式,生成的数据贴合真实业务形态,可有效减少前端联调阶段的边界值误判,提升联调效率。

51、第四、本发明系统自动采集枚举值及其注释、描述信息,并在api文档与mock数据中同步呈现,解决了传统方案仅展示枚举数值、业务含义缺失的弊端,完善测试场景覆盖,降低前后端对枚举定义的理解偏差。

52、第五、本发明方案原生适配java/springboot框架下的restfulapi开发场景,同时架构具备良好扩展性,可进一步迁移应用至其他编程语言与开发框架,适用场景丰富。