

Ask HN: What tools do you use for HTTP/Rest API documentation? - stock_toaster

I have been us Sphinx[1] along with sphinxcontrib-httpdomain[2], and the results seem "ok", but I find the reStructuredText syntax to be awkward and cumbersome. I would vastly prefer something markdown based.<p>I have considered Groc[3], because I think the Stripe[4] api docs are awesome and it seems like literate style api documentation could be a big win for maintainability as well as readability, but was wondering if there are better known alternatives.<p>What tools do you use for maintaining api docs?<p><pre><code>  [1]: https://stripe.com/docs/api
  [2]: http://pythonhosted.org/sphinxcontrib-httpdomain/
  [3]: https://github.com/nevir/groc
  [4]: https://stripe.com/docs/api</code></pre>
======
mahmoudimus
Did you see how Balanced does its HTTP docs?

<https://github.com/balanced/balanced-docs>

~~~
stock_toaster
While interesting, it seems (based on the repo) to be Sphinx with some custom
plugins. Output looks nice though.

~~~
mahmoudimus
Why don't you write markdown and use pandoc to pump out rst?

I find that markdown has no real standard and lacing it for documentation
support is kind of hacked on vs rst which has first class support for
directives.

I'd love to discuss how I can simplify balanced-docs, I want to be able to
make it a service on its own.

Do you have some time to talk?

------
anonfunction
<https://developers.helloreverb.com/swagger/>

~~~
stock_toaster
I also ran across <http://apiary.io> which looks neat too. Both services seem
almost more like ... api discovery tools? Api management services?

I was hoping for something more specifically documentation related, and with
the capacity for self hosting. Both may be worth looking into more though.
Thanks for the ref.

