Standard methods for documenting a RESTful API [closed]

Answer 1

To create understanding/documentation, heavyweight solutions aren't always needed. Examples of (great) heavyweight tools are: IO/Docs / Apigee (although great tools).

For tiny projects that already have a docchain setup (doxygen/phpdoc/phpdoctor/custom/etc) I use the following shellscript to just include the page in the full generated documentation:

https://gist.github.com/4496972

A demo: http://pastie.org/5657190

It just use custom comment-tags in your sourcecode. It can also be a nice starting point for documenting any sourcecode (language).

Answer 2

Sure, REST APIs should ideally use HATEOAS and be hypertext driven (with heavy use of media types), but also having simple human-friendly documentation for developers to work off of is helpful.

Some specific tools that are helpful for generating documentation like this:

• Swagger
  • An open spec for describing REST APIs [ github ]
  • Tools for auto-generating
    • Documentation
    • Code for your API
  • Donated to the OpenAPI initiative and renamed OpenAPI in 2015
• Mashery
  • An open source project [ github ]
  • Tools for generating
    • Documentation
    • An exploration interface for your API
• Apiary and API Blueprint
  • Write the API description in a DSL within markdown
  • Tools for auto-generating
    • Documentation
    • Mock server
  • Seems to be focused on ruby+mac devs
• RAML
  • A spec for describing REST APIs [ github ]
• WADL
  • A spec for writing discoverable API docs with XML
  • Some discussion comparing WSDL and WADL
• APIgee
  • A commercial product with some documentation features
• 3scale
  • A commercial product with some documentation features
• miredot
  • Commercial REST API documentation generator
  • Java specific