Generating Accurate OpenAPI Descriptions from Java Source Code

TL;DR

AutoOAS is a new approach that automatically generates precise OpenAPI descriptions from Java source code, outperforming existing methods in accuracy and detail, especially in handling configurations and data models.

Contribution

AutoOAS introduces a novel technique for extracting detailed REST API descriptions directly from Java source code, addressing limitations of prior approaches.

Findings

AutoOAS achieved the highest precision and recall in identifying API components.

It outperformed Respector by 39% in precision and 35% in recall for parameters.

AutoOAS uniquely handles configuration profiles and detailed data models.

Abstract

Developers require accurate descriptions of REpresentational State Transfer (REST) Application Programming Interfaces (APIs) for a successful interaction between web services. The OpenAPI Specification (OAS) has become the de facto standard for documenting REST APIs. Manually creating an OpenAPI description is time-consuming and error-prone, and therefore several approaches were proposed to automatically generate them from bytecode or runtime information. In this paper, we first study three state-of-the-art approaches, Respector, Prophet, and springdoc-openapi, and present and discuss their shortcomings. Next, we introduce AutoOAS, our approach addressing these shortcomings to generate accurate OpenAPI descriptions. It detects exposed REST endpoint paths, corresponding HTTP methods, HTTP response codes, and the data models of request parameters and responses directly from Java source code. We evaluated AutoOAS on seven real-world Spring Boot projects and compared its performance with the three state-of-the-art approaches. Based on a manually created ground truth, AutoOAS achieved the highest precision and recall when identifying REST endpoint paths, HTTP methods, parameters, and responses. It outperformed the second-best approach, Respector, with a 39% higher precision and 35% higher recall when identifying parameters and a 29% higher precision and 11% higher recall when identifying responses. Furthermore, AutoOAS is the only approach that handles configuration profiles, and it provided the most accurate and detailed description of the data models that were used in the REST APIs.