Automated OpenAPI Generation with Large Language Models

Researchers have developed OOPS (OpenAI OpenAPI Project Scanner), a breakthrough approach that uses large language models to automatically generate OpenAPI specifications from REST API source code across multiple programming languages and frameworks.

The Problem with Current API Documentation

REST APIs power modern web applications, but developers struggle to create and maintain their OpenAPI specifications. These machine-readable documents describe API endpoints, request parameters, and response formats—essential for automated testing, documentation, and integration with AI frameworks.

Existing solutions fall short:

  • Annotation-based tools require developers to manually add framework-specific comments
  • Static analysis tools work only with specific languages like Java Spring Boot
  • Crawler-based approaches need deployed applications and miss unexposed endpoints

OOPS: A Technology-Agnostic Solution

OOPS addresses these limitations through an innovative LLM agent workflow that analyzes source code directly. The system works in three phases:

1. Technology Analysis

An LLM agent identifies the programming language and framework, then uses role-playing to optimize subsequent analysis quality.

2. Endpoint Method Extraction

A multi-agent workflow extracts API endpoints through:

  • File-level detection of API entries across the codebase
  • Dependency analysis using an API dependency graph to associate related files
  • Path integration to construct complete endpoint URLs and HTTP methods

The API dependency graph solves a critical challenge: REST API implementations often span multiple files, but feeding all files to an LLM exceeds context limits. The graph maintains only essential relationships, keeping file associations shallow (maximum 3 levels) while enabling cross-file analysis.

3. OpenAPI Specification Generation

Two specialized agents generate request and response specifications separately, then merge results. This multi-stage approach prevents the complexity that causes single-pass generation to fail.

Overcoming LLM Limitations

OOPS tackles three key challenges when applying LLMs to API specification generation:

Context Length Limitations: The API dependency graph enables targeted file association without overwhelming the model’s context window.

Syntactic Hallucinations: A self-refine strategy detects and corrects JSON syntax errors, invalid references, and format inconsistencies.

Semantic Hallucinations: Multi-stage generation prevents LLMs from mixing OpenAPI versions or generating non-compliant structures.

Impressive Results

Testing on 12 real-world REST APIs spanning 5 programming languages (Java, Python, JavaScript, Go, PHP) and 8 frameworks (Spring Boot, Flask, Express.js, etc.) shows OOPS significantly outperforms existing methods:

  • Endpoint method inference: 98.8% F1-score (41.5% improvement)
  • Request parameter inference: 97.2% F1-score (60.2% improvement)
  • Response inference: 97.0% F1-score (70.4% improvement)
  • Parameter constraint inference: 92.3% F1-score (43.6% improvement)

The system maintains efficiency with average costs of $0.41 per API and input tokens averaging 5.6K (maximum 16.2K).

Key Technical Innovations

API Dependency Graph: Models file relationships at the right granularity—detailed enough for accurate analysis, simple enough to avoid context overflow.

Multi-Agent Workflow: Specialized agents handle distinct tasks (file detection, dependency analysis, specification generation) more effectively than monolithic approaches.

Self-Refine Strategy: Iteratively corrects both syntax errors and semantic inconsistencies in generated specifications.

Practical Impact

OOPS represents the first technology-agnostic LLM-based approach for OpenAPI generation. Unlike previous methods limited to specific frameworks, it adapts to new technologies through LLM understanding rather than manual rule creation.

This breakthrough enables:

  • Automated API documentation for legacy systems
  • Consistent specification quality across diverse codebases
  • Integration with modern AI development workflows
  • Reduced maintenance burden for development teams

The research demonstrates how thoughtful LLM agent design can overcome fundamental limitations, creating practical tools that work across the diverse landscape of modern software development.