API documentation

<p>Good day, </p> <p>I&#39;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.</p> <p>Is there a better way to document API&#39;s? What do you guys use?</p> <hr/>**评论：**<br/><br/>qu33ksilver: <pre><p>I have been using <a href="https://github.com/goadesign/goa/" rel="nofollow">goa</a> successfully in a project. Works very nicely and auto-generates swagger docs from your code.</p> <p>Then I just dump the generated json into swagger-ui to show to my PM. Has worked okay for me so far.</p></pre>Robjloranger: <pre><p>I&#39;ve been working on a project using goa as well and it&#39;s been great.</p></pre>peterhellberg: <pre><p>I use this tool that I wrote: <a href="https://github.com/peterhellberg/hiro" rel="nofollow">https://github.com/peterhellberg/hiro</a></p> <p>Example of service that use Hiro: <a href="https://search.b17g.services/" rel="nofollow">https://search.b17g.services/</a></p></pre>Tikiatua: <pre><p>Graphql and GRPC</p></pre>kemitche: <pre><p>I&#39;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.)</p> <p>What are you finding to be a clusterfuck about it? I might be able to point you in the right direction.</p> <p>(Side note: I hate the annotations approach because it usually degrades into &#34;I must manually keep my annotations up to date with the actual validation logic that happens a few lines down&#34;)</p></pre>