Generating accurate OpenAPI descriptions from Java source code
Alexander Lercher, David Jamnig, Christian Macho, Clemens Bauer, Martin Pinzger · Journal of Systems and Software · 2026
Developers require accurate descriptions of REpresentational State Transfer (REST) Application Programming Interfaces (APIs) for implementing successful interactions 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 source code or runtime information. In this paper, we first study four such state-of-the-art approaches, Respector, Prophet, springdoc-openapi, and Swagger Core, and discuss their shortcomings. Next, we introduce AutoOAS, our approach addressing these shortcomings to generate accurate OpenAPI descriptions. It detects exposed REST API 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 15 real-world Java projects developed with the two popular frameworks Spring Boot and JAX-RS and compared its performance with the four state-of-the-art approaches. Based on a manually created ground truth, AutoOAS achieved the highest precision and recall when identifying REST API endpoint paths, HTTP methods, parameters, and responses. It outperformed the second-best approach, Respector, by 29 percentage points in precision and 27 in recall when identifying parameters, and by 25 percentage points in precision and 34 in recall when identifying responses. Furthermore, AutoOAS generated more accurate OpenAPI data model schemas than the framework-specific approaches springdoc-openapi and Swagger Core, outperforming them by 30 and 14 percentage points, respectively.