Refactor Gin Support: Deprecate AST-based OpenAPI Generation, Add AST-guided Annotation and LLM Workflow

[spencercjh]

Background

Currently, spec-forge aims to support the Gin framework by using deep AST analysis to automatically generate OpenAPI specs, with the goal of replacing ecosystem tools such as swaggo. In practice, we have found:

• Real-world Gin projects have highly diverse handler wrappers, parameter extraction, and response structures. Maintaining and controlling the failure boundaries of AST-powered interface semantics restoration is extremely costly.
• To achieve comprehensive automatic spec generation, AST logic is forced to cover increasing numbers of edge cases, which is unsustainable and prone to uncontrollable errors.
• User trust in the quality of generated specs is limited; significant manual review and adjustment are always needed.

After repeated attempts, we have concluded to abandon the product goal of “fully replacing swaggo by automatically generating an OpenAPI spec via Gin AST.” Gin support should be re-architected into an "AST-guided annotation planning + LLM collaboration" workflow.

---

Core Plan Adjustments

1. Archive/Deprecate the Old Gin AST-based Spec Generation Path

• spec-forge generate gin should be marked deprecated/archived
• Clearly state that this approach is no longer maintained due to high complexity and lack of scalability
• Update README, CLI outputs, and docs to recommend the new approach

2. Add Annotate/Plan-featured Commands as the Main Gin Support Path

Command Design

• Introduce a new command, e.g. spec-forge annotate gin or spec-forge plan gin
• Objective: scan Gin projects, extract routes, handlers, DTOs, parameters, groups, tags, and other context via AST analysis, and generate a Markdown plan.md
• The plan is to provide prompt/reference for R&D or LLM to generate swaggo godoc annotations

Suggested plan.md Content Structure

• One section per endpoint, containing:
  • Method, route, handler, source file
  • Discovered parameters, request/response types (distinguishing between known/inferred/uncertain)
  • Available tags, group/auth hints
  • Suggested annotation skeleton
  • Points explicitly requiring AI/human attention
• The format should be LLM- and human-consumable

Purpose of the Plan

• The plan is not a spec, but a to-do/actionable annotation/documentation roadmap and LLM workflow input
• R&D can leverage it to prompt LLMs to draft swaggo annotations, then review/patch before generating the OpenAPI spec via swaggo/builder type tools

3. Retain enrich/publish Capabilities

• Enrich and publish continue to support OpenAPI post-processing/publication, decoupled from upstream annotation generation
• Next, support can be extended to:
  • Work with multiple sources (swaggo, other frameworks, existing specs)
  • Normalize documentation (tags, contact, terms, etc.)

4. Naming, Architecture, and Implementation Notes

• Use annotate as a command name for clarity (stronger semantics than the generic plan)
• Possible followups:
  • annotate --write for auto patching (dryrun/planning first, then in-place patch)
• Update Gin docs, README, PRs, and issues accordingly

---

Expected Impact

• Sharper project positioning: help dev teams efficiently author/maintain OpenAPI specs, not attempt risky full static automation
• AST analysis remains useful and is not wasted
• Human, AI, and automation strengths are leveraged together
• Lower maintenance costs, higher “productization” and delivery confidence

---

Summary / Next Steps

1. Archive the generate gin workflow
2. Add new annotate gin/plan gin capability for AST-guided annotation planning
3. Keep/improve enrich/publish pipeline, decoupled from annotation entry
4. Update CLI, docs, and README across the project

All agents/maintainers should reference this plan when implementing and updating documentation.