LRASGen: LLM-based RESTful API Specification Generation

Sida Deng, Rubing Huang, Man Zhang, Chenhui Cui, Dave Towey, Rongcun Wang · 2025

Read LRASGen: LLM-based RESTful API Specification Generation by Sida Deng, Rubing Huang, Man Zhang, Chenhui Cui, Dave Towey, Rongcun Wang (2025) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2504-16833.txt.

Introduction

Sida Deng and co-authors use large language models to generate formal specifications for web APIs from their source code. Developers need these OpenAPI documents to use and test services, but writing and updating them by hand is slow and error-prone, especially as requirements change. Their method treats specification writing as a text-generation task.

Notably, the system can still draft a specification when the code is incomplete or lacks annotations. They tested it on twenty real-world APIs with two different language models. Both produced accurate specifications, and the generated documents covered far more of the API's pieces than the developers' own versions had. The approach could cut a tedious chore in software maintenance.

Catalog record

CREATORSida Deng, Rubing Huang, Man Zhang, Chenhui Cui, Dave Towey, Rongcun Wang
YEAR2025
COLLECTIONPAPERS
FORMATTXT
FILE SIZE94 KB
VERSION1.0
LICENSEhttp://creativecommons.org/licenses/by/4.0/
RIGHTSCC BY
SOURCEarXiv

Source: https://arxiv.org/abs/2504-16833

Browse the full library · About the Tower of Babel

Full text

The opening of the work, from the library's hosted text:

LRASGen: LLM-based RESTful API Specification Generation Sida Deng, Rubing Huang, Man Zhang, Chenhui Cui, Dave Towey, Rongcun Wang Abstract . REpresentation State Transfer (REST) is an architectural style for designing web applications that enable scalable, stateless communication between clients and servers via common HTTP techniques. Web APIs that employ the REST style are known as RESTful (or REST) APIs. When using or testing a RESTful API, developers may need to employ its specification, which is often defined by open-source standards such as the OpenAPI Specification (OAS). However, it can be very time-consuming and error-prone to write and update these specifications, which may negatively impact the use of RESTful APIs, especially when the software requirements change. Many tools and methods have been proposed to solve this problem, such as Respector and Swagger Core. OAS generation can be regarded as a common text-generation task that creates a formal description of API endpoints derived from the source code. A potential solution for this may involve using Large Language Models (LLMs), which have strong capabilities in both code understanding and text generation. Motivated by this, we propose a novel approach for generating the OASs of RESTful APIs using LLMs: LLM-based RESTful API-Specification Generation (LRASGen). To the best of our knowledge, this is the first use of LLMs and API source code to generate OASs for RESTful APIs. Compared with existing tools and methods, LRASGen can generate the OASs, even when the implementation is incomplete (with partial code, and/or missing annotations/comments, etc.). To evaluate the LRASGen performance, we conducted a series of empirical studies on 20 real-world RESTful APIs: These studies examined the precision, recall, and F1-score when identifying the four main entities, i.e., endpoint methods and parameters, parameter constraints, and endpoint responses. The results show that two LLMs (GPT-4o mini and DeepSeek V3) can both support LARSGen to generate accurate specifications, and LRASGen-generated specifications cover an average of 48.85% more missed entities than the developer-provided specifications. In addition, compared with the state-of-the-art specification-generation techniques (Respector, Swagger Core, and Springdoc), we can observe: 1) For the 15 Java-based RESTful APIs, LRASGen outperforms all three state-of-the-art OAS generation techniques, which, on average, detect only 75.67% endpoint methods, 75.24% endpoint parameters, 4.78% parameter constraints, and 26.75% endpoint responses. 2) For the remaining five RESTful APIs (developed in Python and C# programming languages), LRASGen achieves 100% precision, recall, and F1-score for all four identification tasks; however, the other three techniques can not be successfully applied (because they are designed for Java-based APIs). DOI: XXXXXXX.XXXXXXX ISBN: 978-1-4503-XXXX-X/18/06 CCS: Software and its engineering Specification languages CCS: Information systems RESTful web services 1. Introduction REpresentational State Transfer (REST) ( Fielding, 2000 ) is an architectural style for designing web applications. It uses typical World Wide Web infrastructure, such as the HTTP protocol, and is characterized by some key principles: Client-Server, Stateless, Cache, Uniform Interface, Layered System, and Code-On-Demand ( Fielding, 2000 ) . Web APIs that follow the REST style can communicate and collaborate over the Internet, regardless of the programming language or framework used to develop them: These kinds of APIs are called RESTful (or REST) APIs ( Masse, 2011 ) . RESTful APIs have been widely adopted, due to their simplicity and the ability to use existing web infrastructure. They typically use standard HTTP request methods (such as GET, POST, PUT, and DELETE) to perform create, retrieve, update, and delete operations on resources ( MDN, 2025a ) . The results of these requests are usually expressed using the standard HTTP response status codes: The 1xx status code indicates information responses; 2xx indicates successful responses; 3xx indicates redirection messages; 4xx indicates client-error responses; and 5xx indicates server-error responses ( MDN, 2025b ) . Modern service providers publish their services online in the form of RESTful APIs to allow subscribers to access text, audio, video, and other types of data ( Neumann et al., 2021 ) . When the RESTful API goes online, it also publishes a specification describing various information about itself. This specification can be in many forms, including the OpenAPI Specification (OAS) and the API blueprint: Currently, OAS is the most popular ( Rehman, 2025 ) . OAS ( Initiative, 2025b ) , formerly known as the Swagger Specification ( Software, 2025 ) , serves as the de facto standard for describing RESTful APIs. It enables both humans and computers to discover and understand the capabilities of a RESTful API, without requiring access to the source code, or necessitating network-traffic inspection. OAS serves as a cornerstone for designing, building, and testing RESTful APIs, providing a clear structure for developers to follow. Despite the importance of the specifications, their quality may often be lacking, hindering effective API use and testing. Poorly maintained or inaccurate specifications can lead to a disconnect between the RESTful API’s intended use, and its actual implementation: This can result in integration issues or potential security vulnerabilities. As RESTful APIs evolve, keeping the specification and the implementation synchronized becomes increasingly difficult, potentially resulting in incomplete or inconsistent specifications. A primary challenge relates to the manual creation and maintenance of the specification, which is time-consuming and error-prone. This can be compounded by things like changing requirements, developers’ poor writing skills, etc. To address these challenges, various tools and methodologies have been proposed to automate specification generation ( Huang et al., 2024 ; Lercher et al., 2024 ; Software, 2025 ; Springdoc, 2025 ) . However, these solutions often rely on annotations within the code, require manual intervention, or cannot identify complex API behaviors. Swagger Core ( Software, 2025 ) infers framework-specific and technique-specific annotations at runtime to generate specifications. Similarly, Springdoc ( Springdoc, 2025 ) also requires annotations for specification generation: Without correct annotations, it is not possible to generate correct specifications. These limitations have led to the exploration of static analysis techniques: Respector ( Huang et al., 2024 ) uses static analysis technology to generate the specifications directly from the source code, removing the need for additional annotations, and reducing the maintenance burden. Whether it is an annotation-based approach, code-based methods, configuration-based techniques, or manual writing, understanding the source code is key to successfully generating an appropriate specification, such as OAS. OAS generation can be regarded as a text-generation task that creates a formal description of API endpoints derived from the source code. Recent studies ( Hou et al., 2024 ) have shown that Large Language Models (LLMs) have excellent potential for code-understanding and text-generation tasks, which are precisely what is needed to understand API source code and generate OASs. In this research, we introduce a novel approach: LLM-based RESTful API-Specification Generation (LRASGen). LRASGen is designed to revolutionize the way RESTful API specifications are generated. LRASGen identifies endpoint methods, endpoint parameters, parameter constraints, and endpoint responses directly from the source code: It uses LLMs to do this, ensuring that the generated specification is consistent with the API implementation, and automatically updates as the source code changes. LLMs can be especially useful in situations where, for example, parts of the source code are not available, the structure is incomplete, or maybe some parameters are not fully defined: LRASGen can then use the LLMs to generate reasonable specifications. To the best of our knowledge, LRASGen is the first

Read the complete text