Ask HN: What tools do you use for HTTP/Rest API documentation? | Hacker News Reader

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

3 pointsstock_toaster5 comments

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

Did you see how Balanced does its HTTP docs?

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

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

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?

https://developers.helloreverb.com/swagger/

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.

Reply on news.ycombinator.com