Best API Documentation Tool

Options:
APIGEE SmartDocs
Swagger
turnapi
Custom Website

3Scale.net - Active Docs (Use Swagger as Specification) [Out]
   https://support.3scale.net/howtos/api-configuration#active-docs


Not Candidates:
Docco
Dexy

Tools:
Doxygen

Best API Platform:
1. WSO2 API Management
2. APIGEE
3. Mashery
4. Layer 7
5. 3scale
6. Mulesoft

Evaluation Considerations:
1. Out-of-the box developer Tool
2. UI Experience
3. Language Agnostic
4. Code Level Documentation
5. Support JSON and XML
6. Support WADL
7. Demo/Documentation
8. Modify documentation directly on the system, instead of code.
9. Customers
10. Google Trends
11. Open Source
12. Sync with Git
13. Swagger-based documentation
14. Scalability to support chosen API Management Platform
15. Compatible with different REST publishing Framework - JAX-RS

Directions/Principles:
1. Choose the API Doc tool which can work with corresponding API Management Platform.
2.

API Platform:
APIGEE
Mashery

Directoins:
1. I would lean towords using API Docs with APIGEE
2.

Learnt:
1. Docco is not good for API Documentation
2. SOA strategies mostly target internal users; open Web APIs target mostly external partners. So API management requires developer portals, key management, and metering and billing facilities that SOA
management never provided.
3. API management platforms deliver important additional capabilities: developer portals, key management and approval, and metering and billing. Most companies don’t support these requirements in their existing SOA governance strategies.
4. Examples of vendors with API-native solutions are 3scale and Mashery
5. Examples of vendors with SOA-native solutions are IBM, Layer 7, and Vordel
6. Another solution vendor that began in this market segment but is now targeting API management is Apigee, formerly Sonoa Systems. Apigee’s API management platform bears some resemblance to Mashery’s cloud-based developer portal.
7.

Knowledge Sharing:
1. It does, however, require the capabilities of the service be described in the structure of the Swagger Specification. Not all services can be described by Swagger--this specification is not intended to cover every possible use-case of a REST-ful API. Swagger does not define a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a REST API.

API Platform Comparision:
http://www.ca.com/us/~/media/Files/IndustryAnalystReports/The-Forrester-Wave-API%20Management-Q1-2013.pdf

References:
http://mestachs.wordpress.com/2012/08/06/rest-api-documentation/