You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@answer.apache.org by "LinkinStars (via GitHub)" <gi...@apache.org> on 2026/07/20 15:36:21 UTC

[I] Swagger-generated API documentation does not accurately describe the current API surface [answer]

LinkinStars opened a new issue, #1557:
URL: https://github.com/apache/answer/issues/1557

   ### Background
   Apache Answer uses [swaggo/swag](https://github.com/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.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@answer.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@answer.apache.org
For additional commands, e-mail: issues-help@answer.apache.org


Re: [I] Swagger-generated API documentation does not accurately describe the current API surface [answer]

Posted by "AsyncAssassin (via GitHub)" <gi...@apache.org>.
AsyncAssassin commented on issue #1557:
URL: https://github.com/apache/answer/issues/1557#issuecomment-5713116545

   @LinkinStars, I’d like to help with this incrementally. 
   
   For a first PR, I propose documenting 
   `GET /answer/admin/api/users/page` and 
   `GET`/`POST /answer/admin/api/user/activation`: 
   correct the POST path, 
   type the pagination `list`, 
   fix filter descriptions/defaults, and 
   document admin access, errors, and activation side effects.
   
   I’d regenerate the Swagger files without changing runtime behavior. 
   Would this scope work? 
   This would address part of #1557, not close it.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@answer.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@answer.apache.org
For additional commands, e-mail: issues-help@answer.apache.org


Re: [I] Swagger-generated API documentation does not accurately describe the current API surface [answer]

Posted by "AsyncAssassin (via GitHub)" <gi...@apache.org>.
AsyncAssassin commented on issue #1557:
URL: https://github.com/apache/answer/issues/1557#issuecomment-6155816354

   Hi @LinkinStars, following up on the scope proposed above. Would those three admin API operations be a good starting point for a first PR?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@answer.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@answer.apache.org
For additional commands, e-mail: issues-help@answer.apache.org