Good day,
I've been using swagger as an api documentation tool, usually using the go swagger with the doc-first approach. This results in a clusterfuck of generated code with a json file 10 billion lines long that has nothing to do with the code you wrote. On the other hand, doing it the other way round results in a clusterfuck of annotations in the code.
Is there a better way to document API's? What do you guys use?
评论：
qu33ksilver:
Robjloranger:I have been using goa successfully in a project. Works very nicely and auto-generates swagger docs from your code.
Then I just dump the generated json into swagger-ui to show to my PM. Has worked okay for me so far.
peterhellberg:I've been working on a project using goa as well and it's been great.
Tikiatua:I use this tool that I wrote: https://github.com/peterhellberg/hiro
Example of service that use Hiro: https://search.b17g.services/
kemitche:Graphql and GRPC
I've been using go-swagger to much success. (There was a bit of learning curve to get things integrated in my workflow, once I sorted that out I reached a point where I can entirely ignore the generated code directory and focus on the business logic.)
What are you finding to be a clusterfuck about it? I might be able to point you in the right direction.
(Side note: I hate the annotations approach because it usually degrades into "I must manually keep my annotations up to date with the actual validation logic that happens a few lines down")
