AI API Contract Extractor

Extract REST API endpoints and infer request/response schemas from a Git repository using Java, Spring Boot, and LLMs.

AI API Contract Extractor scans a GitHub or GitLab repository, detects supported API endpoints, and produces a structured JSON representation of their methods, paths, and inferred schemas.

Built to explore backend architecture, extensible framework detection, bounded concurrency, and resilient LLM integration.

Key Features

• Multi-framework endpoint extraction — strategy-based detection for supported Spring Boot and Express.js patterns.
• LLM-powered schema inference — uses LangChain4j to infer request and response schemas from source-code context.
• Heuristic fallback — falls back to heuristic schema extraction when LLM inference fails or returns unusable output.
• Bounded concurrency — limits concurrent schema-generation requests to control resource usage and API costs.
• Endpoint deduplication — deduplicates detected endpoints by HTTP method and path.
• Repository lifecycle management — shallow, time-bounded clones with temporary-directory cleanup.
• Input validation and error handling — validates repository URLs and provides consistent error responses.

Architecture

flowchart TD
    A["Client"] --> B["POST /api/extract"]
    B --> C["Validate Repository URL"]
    C --> D["GitService"]
    D --> E["Clone Repository"]
    E --> F["RepoScannerService"]
    F --> G["EndpointExtractorService"]
    G --> H["Framework Strategy"]
    H --> I["Extract Code Context"]
    I --> J["SchemaGeneratorService"]
    J --> K{"LLM inference successful?"}
    K -- Yes --> L["LLM-generated schemas"]
    K -- No --> M["Heuristic fallback"]
    L --> N["Build structured JSON response"]
    M --> N
    N --> O["Return API endpoints and schemas"]
    D -. "Cleanup temporary clone" .-> P["Remove cloned files"]

Loading

Design Decisions

Decision	Why it matters
Strategy pattern	Makes framework-specific endpoint extraction extensible without changing the orchestration flow.
Bounded thread pool	Prevents unbounded concurrent LLM calls when processing larger repositories.
Heuristic fallback	Allows schema extraction to degrade gracefully when LLM inference is unavailable or unusable.
Temporary clone cleanup	Prevents cloned repository files from accumulating between requests.
Centralized exception handling	Keeps API error responses consistent.

Tech Stack

• Language: Java 21
• Backend: Spring Boot 3.3
• LLM integration: LangChain4j with an OpenAI-compatible endpoint
• Repository operations: JGit
• Concurrency: ExecutorService
• Testing: JUnit 5, Mockito, AssertJ
• Build: Maven

Getting Started

Prerequisites

• JDK 21
• Git
• An LLM API key configured for your chosen provider

1. Configure the LLM API key

For the default Groq configuration, set the key in your shell:

export GROQ_API_KEY=your_key_here

On Windows PowerShell:

$env:GROQ_API_KEY = "your_key_here"

Never commit API keys or other secrets to the repository.

2. Build and run

On Linux or macOS:

./mvnw clean spring-boot:run

On Windows:

.\mvnw.cmd clean spring-boot:run

The server starts at:

http://localhost:8080

3. Extract API contracts

Send a repository URL to the extraction endpoint:

curl -X POST http://localhost:8080/api/extract \
  -H "Content-Type: application/json" \
  -d '{"repoUrl":"https://github.com/OWNER/REPOSITORY"}'

Replace OWNER/REPOSITORY with a repository you are authorized to inspect.

By default, the application allows GitHub and GitLab hosts, subject to its configured allowlist.

4. Example response

The following is an illustrative response showing the intended output shape:

{
  "endpoints": [
    {
      "method": "POST",
      "path": "/jobPost",
      "sourceFile": "JobController.java",
      "requestSchema": "{\"title\":\"string\",\"description\":\"string\"}",
      "responseSchema": "{\"id\":\"integer\",\"status\":\"string\"}"
    }
  ]
}

The actual endpoints and schemas depend on the source repository and the information available to the extraction pipeline.

5. Run tests

./mvnw test

Configuration

The following settings are documented in the current implementation's application.properties.

Property	Default	Purpose
extraction.schema-generation-limit	5	Maximum endpoints selected for LLM schema generation per request
extraction.schema-generation-threads	2	Maximum concurrent schema-generation workers
extraction.llm-call-delay-millis	250	Configured delay between LLM calls per worker
repo.allowed-hosts	github.com,gitlab.com	Permitted repository clone hosts
repo.clone-timeout-seconds	60	Clone timeout

Verify the current property names and defaults in application.properties before changing them.

Project Structure

The main components documented in the implementation include:

src/
├── main/
│   ├── java/
│   │   └── .../
│   │       ├── service/
│   │       │   ├── ExtractionService.java
│   │       │   ├── EndpointExtractorService.java
│   │       │   ├── SchemaGeneratorService.java
│   │       │   ├── RepoScannerService.java
│   │       │   ├── GitService.java
│   │       │   └── strategy/
│   │       ├── agent/
│   │       ├── dto/
│   │       ├── exception/
│   │       └── model/
│   └── resources/
└── test/
    └── java/

This is a simplified overview; consult the source tree for the complete package layout.

Limitations

• Endpoint detection is pattern-based for supported frameworks and is not guaranteed to recognize every valid route declaration.
• Schema inference depends on the available source-code context and the quality of the LLM response.
• LLM-generated schemas are estimates, not verified API contracts.
• The number of endpoints selected for LLM inference is bounded by configuration.
• Framework-specific syntax and unusual code patterns may not be detected correctly.

Security Considerations

• Only inspect repositories you are authorized to access.
• Keep LLM credentials in environment variables or a secret manager.
• Keep repository-host allowlisting and clone timeouts enabled.
• Treat repository contents and generated schemas as untrusted input.
• Review clone cleanup