Documentation tools for RPC APIs

Question

There are a variety of good tools out there for source code and API documentation (doxygen, Headerdoc, Sphinx, to name but a few). However, none of them appear especially good at producing documentation for APIs that are provided via an RPC interface (if you have recommendations on how to synthesize RPC API documentation with these tools, by all means suggest it).

I am specifically interested in documentation tools which have at least some support for JSON and AMQP, but the question would also stand for things like Protobuf, Thrift, and XML-RPC and any tool suggestions that work with those technologies would at least give me a place to start.

I honestly have yet to see quality documentation for any RPC interface (either produced by hand or by a tool), and I'm just hoping that's because developers are lazy and not because the tools don't exist.

Answer 1

Take a look at Swagger (http://swagger.wordnik.com) - this is what we use for all our apis at 3scale (http://www.3scale.net). Basically it'll take a JSON spec and do various things including create interactive API docs for you. RPC style docs should be fine (we amended it to take / receive XML). There are also tools for generating the specs from code for various languages.

Lastly, there's a simple code extractor tool which can create the JSON: https://github.com/solso/source2swagger. All this is less formalised than Doxygen etc. but might be useful to check out.