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

Bắt đầu bằng cách so sánh các handler và annotation trong internal/controller và internal/controller_admin với docs/swagger.json, docs/swagger.yaml và docs/docs.go. Rà soát các route chưa được tài liệu hóa và các response sơ sài, sau đó đồng bộ các annotation và artifact được tạo để reference được tạo bao phủ toàn bộ API hiện tại, bao gồm các response hữu ích, các lỗi và các tag nhất quán.

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.