New LLM Approach Automates REST API Documentation, Catching Gaps Developers Miss

Writing and maintaining documentation for RESTful APIs is a notorious pain point for software development teams. The specifications themselves—typically defined using standards like the OpenAPI Specification (OAS)—are crucial for both internal developers and external users trying to understand how an API works. Yet the process remains tedious, error-prone, and often falls behind as requirements shift.

Researchers have now proposed a novel solution: using large language models (LLMs) to generate these specifications automatically from API source code. Their approach, called LRASGen (LLM-based RESTful API Specification Generation), is believed to be the first of its kind to harness LLMs for this purpose.

How It Works#

LRASGen treats API specification generation as a text-generation problem—feeding the source code of a REST API into an LLM, which then produces a formal OpenAPI description of the endpoints, parameters, and responses. The innovation lies not just in using LLMs, but in their ability to work with incomplete or messy code. Unlike traditional tools such as Respector and Swagger Core, LRASGen can extract meaning even when implementations lack full annotations, inline comments, or are only partially written.

Real-World Testing#

The researchers tested their approach on 20 real-world RESTful APIs using two LLM models: GPT-4o mini and DeepSeek V3. Both successfully generated accurate specifications. More tellingly, the LLM-generated specs uncovered an average of 48.85% more missing entities compared to what developers had originally documented—revealing gaps that were hiding in plain sight.

Why It Matters#

This work addresses a longstanding friction point in API development. When documentation lags behind code, or when teams move fast and skip formal specs, both usability and testing suffer. By lowering the barrier to creating and updating API specifications, LRASGen could help teams stay compliant with standards while freeing developers from tedious manual documentation work.

Full paper: arXiv:2504.16833