ADR-0013: Separate API Toolkit Project (No SpringDoc)

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

Context

API documentation generation needs to produce per-portal, per-chain OpenAPI specs from backend source code. Two approaches were considered: embedding documentation generation into the backend (e.g., SpringDoc/Swagger annotations at runtime) or building an external tool that reads source code statically.

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

Decision

Documentation is generated by a separate project (slaunchx-api-toolkit) that reads Java source files as input and produces OpenAPI JSON as output, without any runtime dependency in the backend. The backend stays clean of documentation annotations. The toolkit uses JavaParser for AST analysis and FreeMarker for template-based documentation generation. It runs as a CI step, not as part of the application runtime.

Consequences

• Backend has zero documentation-related dependencies (no SpringDoc, no Swagger annotations).
• The toolkit can evolve independently of the backend's Spring Boot version.
• Documentation generation is deterministic: same source code always produces the same output (no runtime state dependency).
• The parser must understand the backend's annotation conventions (@GatewayValidation, @ApiScope, etc.) but this is a read-only coupling.
• Three existing Python scripts (java_to_openapi.py, merge_specs.py, validate_spec.py) are replaced in a single cutover PR.

Alternatives Considered

• SpringDoc with runtime scanning: Rejected because it adds runtime dependencies, requires a running application context for doc generation, and cannot distinguish portal/chain scopes without custom extensions.
• Swagger annotations on controllers: Rejected because it pollutes the controller code with documentation concerns and creates a dual-annotation burden alongside the existing gateway annotations.
• Keep the Python regex parser: Rejected (see ADR-0004) because regex-based parsing is fundamentally limited for Java source analysis.