I am working on a REST API implemented in go. I have already wrestled with godoc
As someone used to Doxygen, I find godoc and apidoc.js to be very limiting.
Has magic comments starting with "swagger:" like
// swagger:route GET /pets pets users listPets
While https://github.com/swaggo/echo-swagger uses comments prefixed with an @ like:
// @title Swagger Example API // @version 1.0
echo-swagger appeals because I have also inherited a preference to use labstack/echo from the same colleagues
Swaggo also uses @ prefixed comments but I'm not sure its the same format:
// @Param enumstring query string false "string enums" Enums(A, B, C)
I recall there was a competitor to swagger. Googling I only came up with openAPI. It seems swagger2.0 == openAPI 2.0 so I guess they merged. Then I discovered openAPI 3.0 exists and go-swagger doens't yet support it
There also seem to be RAML and API blueprint too.
I'm leaning towards swagger.io as its documentation seems more complete. What do typical gophers (or engineers in other languages) prefer and why?
There is another question which asks this for Java and ironically gives the answer Doxygen. I am not aware of any good examples of REST documentation in Doxygen though. I'm not sure it would be a good fit outside of its comfort zone. It doesn't officially support go yet