Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 6 years ago.
Many questions have been posted and answered about REST / HTTP based APIs, etc, but none seem to have much information on the following question:
What tools are available/used to document a HTTP-RPC API?
Which tools are the best?
A Similar question (specific to ASP.NET) from Jan 2009 can be found here, but with no answers.
I am in the process of developing several APIs both professionally and for personal projects (.NET MVC/OpenRasta, PHP, Coldfusion, etc..), and I haven't found anything in particular to help document these APIs. I am not looking for auto-generation based on code-parsing/scrubbing or anything like that. As you probably already know a RESTful/HTTP-based API should be client and platform agnostic; as such I would expect any documentation tool to be the same.
Features that a decent tool might have:
- 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)
- Auto-generate static reference files/documentation like the examples below
- Include examples, test-cases, etc
Here are some examples of what I consider decent API documentation/reference(s) look like:
http://dev.twitter.com/doc/post/statuses/destroy/:id
http://www.salesforce.com/us/developer/docs/api_rest/index.htm
http://www.flickr.com/services/api/
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.
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!
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.
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.
