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

首先将 internal/controller 和 internal/controller_admin 中的处理器和注解与 docs/swagger.json、docs/swagger.yaml 以及 docs/docs.go 进行比较。检查未记录文档的路由和内容浅显的响应，然后使注解与生成的构件保持一致，以便生成的参考文档覆盖当前的 API 范围，包括有用的响应、失败情况和一致的标签。

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.