I am working on a REST API implemented in go. I have already wrestled with godoc

Colleagues have started using apidoc.js but I have found in lacking in several areas. For example I don't even know how to insert a simple comment.

As someone used to Doxygen, I find godoc and apidoc.js to be very limiting.

swagger looks like it might be a better option but there seem to be several possibly competing or superseded ways of writing comments. For example: https://goswagger.io/use/spec/route.html

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

  • I'm not 100% clear if I would be better of asking this on softwareengineering or here but it is basically a recommendation question. – Bruce Adams Nov 12 '18 at 18:37
  • Do you have an example of what you think REST API documentation should look like? – Mawg says reinstate Monica Nov 13 '18 at 13:15
  • 1
    That is a whole other question - stackoverflow.com/questions/4937379/… - with some useful answers. – Bruce Adams Nov 13 '18 at 23:06
  • And what a great question it is too (ah! for the days when we could about tools - and books - and even use the word "best" - on S.O). Did you check out REST Tool? If you do get an answer, please post it here and accept it, as that would be very useful to others in future. Thanks – Mawg says reinstate Monica Nov 14 '18 at 7:20
  • 1
    I'm leaning towards go-swagger so far but more as a schilling point than for any technical reason. – Bruce Adams Nov 14 '18 at 19:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.