3 ms·
Ask HN: What tools do you use for HTTP/Rest API documentation?
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.
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.
What tools do you use for maintaining api docs?
[1]: https://stripe.com/docs/api
[2]: http://pythonhosted.org/sphinxcontrib-httpdomain/
[3]: https://github.com/nevir/groc
[4]: https://stripe.com/docs/api
- mahmoudimus 14y agoDid you see how Balanced does its HTTP docs? https://github.com/balanced/balanced-docs https://github.com/balanced/balanced-docs
- stock_toaster 14y agoWhile interesting, it seems (based on the repo) to be Sphinx with some custom plugins. Output looks nice though.
- mahmoudimus 14y agoWhy 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 14y agohttps://developers.helloreverb.com/swagger/ https://developers.helloreverb.com/swagger/
- stock_toaster 14y agoI also ran across http://apiary.io 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.