What is the best tool for documenting/generate reference for a RESTful/HTTP RPC API? [closed]

Answer 1

One of the reasons such a tool does not exist is because the documentation of a RESTful API should NOT include any of these items:

• Specify URLs/URIs format/structure
• Request/Response formats and methods (GET/POST/etc, XML/JSON/etc)
• Categorize endpoints/API Calls (such as grouping several calls under Authentication)

RESTful API documentation is about documenting media types used and their associated application semantics. You should be looking to produce something that looks more like this.

The examples you have given are HTTP based RPC APIs which is why they require this type of endpoint documentation. They are RESTful in name only. Now, why people are not creating tools to automatically document HTTP based RPC APIs, I can't really tell you. Maybe it is because the people who are writing those APIs are so busy maintaining them that they don't have time to writing documentation tooling!

Answer 2

After much research I have discovered this is no tool that does exactly what I want. There a number of tools that are very much a step in the right direction, but are often language specific, and do not generate HTTP API/RPC Reference documentation, but rather Code/Library/API reference documentation.

As a result I plan on creating the tool the I require/envision from scratch. If/when I have something to show I will update my answer.

Answer 3

You should take a look at the Swagger application, as already mentioned by @zim2001. It has a Swagger-ui component, which is a simple html and javascript application reading the json data recorded by the backend application. There are adapters for number of languages, including php and java.

If you are using the Symfony2 framework for PHP, here's ready-to-use bundle for automatic generation of the RESTful service documentation:

• https://github.com/nelmio/NelmioApiDocBundle

One thing I don't like about such generators is the lack of translations, so if you want to provide the documentation of your API exposed over RESTful services on many languages - you cant.

Answer 4

SWAGGER is probably worth a look for you need. I use it for documenting REST entrypoints exposed by a java application using Jersey, but it looks like you can use it with other languages too.