Generating Accurate OpenAPI Descriptions from Java Source Code

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.