Swagger-generated API documentation does not accurately describe the current API surface

Inizia confrontando gli handler e le annotazioni in internal/controller e internal/controller_admin con docs/swagger.json, docs/swagger.yaml e docs/docs.go. Esamina le route non documentate e le risposte scarne, quindi allinea le annotazioni e gli artefatti generati in modo che il riferimento generato copra la superficie API attuale, includendo risposte utili, errori e tag coerenti.

Background

Apache Answer uses swaggo/swag to generate its REST API documentation from annotations in the Go controllers. The generated artifacts (docs/swagger.json, docs/swagger.yaml, and docs/docs.go) are intended to be the authoritative API reference for contributors, integrators, and third-party developers. However, the source annotations have drifted away from the actual implementation over time, so the generated docs no longer fulfill that role.

Current Situation

The codebase currently has roughly 50 controller files under internal/controller and internal/controller_admin, exposing approximately 221 HTTP routes. The generated docs/swagger.json contains only 161 paths, meaning a significant portion of the API is undocumented. Several controller files, including those for newer features such as AI chat completions, user-center plugins, and MCP tools, contain HTTP handlers with no Swag annotations at all.

For the endpoints that are documented, the annotations are often too shallow to be useful. @Description frequently repeats @Summary verbatim (for example, “delete question” or “GetOtherUserInfoByUsername”), giving callers no insight into behavior, required permissions, side effects, or valid parameter values. Many list and detail endpoints declare their success response as a bare string placeholder ({string} string "") instead of the real response schema, so consumers cannot see the actual field structure they will receive. No controller file currently uses @Failure, so error status codes, reason codes, and error body shapes are entirely absent from the documentation.

Tags are also applied inconsistently. Related endpoints are grouped under different tag names, and the generated swagger.json currently contains no top-level tag definitions, which prevents the Swagger UI from presenting the API in a clean, navigable structure.

Why This Needs to Be Fixed

Accurate API documentation is essential for an open-source project like Apache Answer. New contributors need it to understand the system without reading every handler. Third-party developers and client applications need it to integrate correctly. When the generated Swagger docs are incomplete or misleading, integration work becomes slower and more error-prone, and undocumented endpoints effectively become hidden private APIs that are risky to change or maintain.

The goal is to bring the Swag annotations and the generated Swagger artifacts back into alignment with the real API, so that docs/swagger.json and docs/swagger.yaml can serve as a complete, correct, and usable API reference.