ADR-0004: AST Parser Over Regex for API Documentation

Status: ACCEPTED Date: 2026-03-27 Scope: workspace Supersedes: N/A Superseded by: N/A

Context

The existing API documentation toolchain (java_to_openapi.py, ~1850 lines) uses regex-based parsing to extract endpoint metadata from Java source files. This approach is fragile: it cannot reliably resolve nested types, generic parameters, annotation inheritance, or multi-line expressions. Edge cases required continuous patching.

Source: DevPortal design spec (2026-03-27-devportal-design.md, AD-2, Q1)

Decision

Replace the Python regex parser with a Java CLI tool (slaunchx-api-toolkit) built on JavaParser 3.x for AST-based source code analysis. The parser reads Java source files into a full abstract syntax tree, resolving annotations (@GatewayValidation, @ApiScope, @RequestMapping, etc.), return types, and request/response models with complete type information. Chain-aware separation (WEB vs API) happens at the parser layer, not as post-processing.

Consequences

• Precise extraction: no regex edge cases; full type resolution including generics and nested classes.
• Stable across Java language evolution (JavaParser tracks Java versions).
• Single Java toolchain (parser + FreeMarker templates + PicoCLI) replaces three Python scripts.
• Requires Java runtime in CI (already available since the backend is Java).
• Three-way merge logic for human-edited descriptions is preserved via a migration baseline.

Alternatives Considered

• SpringDoc / Swagger annotations: Rejected (AD-1) because it couples documentation metadata to the backend codebase and adds a runtime dependency.
• Improved regex parser: Rejected because the fundamental limitation (no AST) means every new annotation pattern requires a new regex rule.
• Reflection-based scanning at runtime: Rejected because it requires a running application context and cannot extract Javadoc comments or annotation parameter expressions.