基于Java源代码的精确OpenAPI描述自动生成方法研究

《Journal of Systems and Software》：Generating accurate OpenAPI descriptions from Java source code

　　

开发人员需要精确的表述性状态转移（REpresentational State Transfer，REST）应用程序编程接口（Application Programming Interface，API）描述，以实现网络服务之间的成功交互。OpenAPI规范（OpenAPI Specification，OAS）已成为记录REST API的事实标准。手动创建OpenAPI描述既耗时又容易出错，因此，已有多种方法被提出用于从源代码或运行时信息自动生成这些描述。 本文首先研究了四种此类最先进的方法，即Respector、Prophet、springdoc-openapi和Swagger Core，并讨论了它们的不足之处。接下来，研究人员介绍了AutoOAS，这是研究人员为解决这些不足而提出的方法，用于生成精确的OpenAPI描述。该方法直接从Java源代码中检测暴露的REST API端点路径、相应的HTTP方法、HTTP响应代码以及请求参数和响应的数据模型。 研究人员在15个使用两种流行框架Spring Boot和JAX-RS开发的真实世界Java项目上评估了AutoOAS，并将其性能与四种最先进的方法进行了比较。基于手动创建的真实基准（ground truth），AutoOAS在识别REST API端点路径、HTTP方法、参数和响应方面取得了最高的精确率和召回率。在识别参数方面，其精确率和召回率分别比排名第二的Respector方法高出29个百分点和27个百分点；在识别响应方面，分别高出25个百分点和34个百分点。此外，AutoOAS生成的开源API数据模型模式比框架特定的方法springdoc-openapi和Swagger Core更精确，分别高出30个百分点和14个百分点。

一、研究背景与问题提出

REST（表述性状态转移）API广泛应用于网络服务间的通信，而OpenAPI规范（OAS）已成为描述REST API的事实标准。精确的OpenAPI描述对于API的文档化、测试、可视化及代码生成等下游工具至关重要。然而，手动创建OpenAPI描述耗时且易错，并易导致源代码与描述文档的偏离。现有的自动化方法存在诸多局限：部分方法（如springdoc-openapi、Swagger Core）需要运行目标服务，依赖有效的运行配置和基础设施资源；静态分析方法Respector和Prophet则存在对Spring运行时配置（profiles）支持不足、遗漏框架注解、异常到HTTP状态码的转换错误以及数据模型描述不准确等问题。因此，本研究旨在解决现有方法的不足，提出一种能够从Java源代码直接生成精确且详细OpenAPI描述的静态分析方法AutoOAS。

二、研究内容与结论

研究人员提出了AutoOAS，一种基于Spoon的静态分析工具，支持Spring Boot和JAX-RS两大主流Java框架。AutoOAS从源代码中提取REST API操作（端点路径与HTTP方法）、参数、响应及数据模型，并生成符合OAS规范的描述文档。其核心创新包括：考虑Spring运行时profiles，为每个profile生成独立的OpenAPI描述；支持广泛的框架注解（如表6所列）；准确处理异常到HTTP状态码的转换（包括内置异常、@ExceptionHandler和ExceptionMapper）；精确描述数据模型，包括继承关系（使用allOf关键字）、Map结构（使用additionalProperties）及Bean Validation约束。

为评估AutoOAS，研究人员构建了改进的数据集（GT+），包含7个Spring Boot和8个JAX-RS项目，手动修正了原始基准文档中的错误（如路径前缀缺失、参数名错误、默认响应码错误等），并额外创建了16个GT+ OpenAPI描述作为数据模型表示精度的基准。评估结果显示，AutoOAS在识别API操作、参数和响应码方面均取得了最高的精确率和召回率。在参数识别上，其精确率和召回率分别比Respector高出29和27个百分点；在响应识别上，分别高出25和34个百分点。在数据模型模式生成方面，AutoOAS比springdoc-openapi和Swagger Core分别精确30和14个百分点。此外，AutoOAS无需编译或运行服务，简化了生成流程。

三、关键技术方法

AutoOAS采用Spoon解析并静态分析Java源代码及其继承层次和注解，无需字节码或运行中的服务。其分析流程分为三阶段：首先解析源代码，识别控制器类（如@RestController、@Path）并分配运行时profiles；其次分析API操作、参数和响应，包括从注解提取路径和方法、识别参数位置（路径、查询、头、请求体、表单）、分析返回类型和异常处理逻辑（内置异常、@ExceptionHandler、@ControllerAdvice、ExceptionMapper）以确定响应码；最后生成数据模型，将简单类型直接嵌入描述，将自定义类作为命名模式（named schemas）置于#/components/schemas部分，并处理继承（allOf）、Map（additionalProperties）及Bean Validation约束。评估所用数据集包含15个真实项目，研究人员手动验证并修正了原始基准，创建了GT+文档和GT+ OpenAPI描述。

四、研究结果

4.1 现有方法的不足（RQ1）

通过对比分析，研究人员发现现有方法存在多项不足：Respector不支持Spring profiles，忽略@ApplicationPath注解，错误报告@ModelAttribute参数为请求体对象，遗漏@JsonProperty注解，无法正确处理内置和自定义异常处理逻辑，且不生成命名模式。Prophet无法解析路径中的常量和正则表达式，错误处理@RequestMapping注解，不报告响应码。springdoc-openapi和Swagger Core需要运行服务，且springdoc-openapi扁平化继承信息，Swagger Core仅在特定注解下报告继承。

4.2 操作、参数和响应码检测精度（RQ2）

基于GT+文档的评估表明，AutoOAS在识别API操作、参数和响应码方面均达到最高精确率和召回率。在参数识别上，AutoOAS的精确率和召回率分别比Respector高出29和27个百分点；在响应识别上，分别高出25和34个百分点。AutoOAS正确处理了Spring profiles、@ApplicationPath、路径常量、正则约束、@ModelAttribute、@FormParam、@JsonProperty及异常处理等场景。

4.3 OpenAPI描述表示精度（RQ3）

基于GT+ OpenAPI描述的评估显示，AutoOAS生成的数据模型模式比springdoc-openapi和Swagger Core更精确，分别高出30和14个百分点。AutoOAS正确使用#/components/schemas部分生成命名模式，通过allOf保留继承信息，通过additionalProperties描述Map值类型，并支持Bean Validation约束。

4.4 运行时性能（RQ4）

AutoOAS作为静态分析工具，无需编译或运行服务，相比需要运行环境的springdoc-openapi和Swagger Core，简化了生成流程并降低了资源需求。

五、讨论与结论

讨论部分指出，AutoOAS通过考虑运行时profiles、异常处理和精确数据模型表示，解决了现有方法的系统性不足。其生成的OpenAPI描述可直接用于下游工具，且描述可合并（paths不相交，schemas相同或不相交）。研究结论强调，AutoOAS在检测REST API操作、参数、响应码及生成数据模型模式方面均优于现有最先进方法，为从Java源代码自动生成精确OpenAPI描述提供了有效方案。