originally posted on the Intridea blog here: http://www.intridea.com/blog/2014/1/22/keepin-your-api-honest
We've all come across API documentation that is out of date, lacking details, or just plain wrong! Often times an API’s documentation is entirely separate from the code itself, and there is no verification of the documentation's accuracy.
So how do we overcome this? Well, one solution for this problem is to generate the documentation as a result of passing acceptance tests.
The rspec_api_documentation gem allows you to write specs that generate HTML formatted documentation. The rake task included for running your doc specs is rake docs:generate, which puts the HTML files in the project's ./doc directory. If any specs fail, the documentation doesn't generate.
Once the documentation is generated, it’s time to add a documentation viewer to your API server.
There are two gems for serving API documentation:
Mounting the API documentation server as part of your API server and running rake docs:generate as part of the deployment process ensures your documentation is up to date and available.
So, if you're going to create an API, use grape, rspec_api_documentation, and raddocs to ensure testable, accurate, and up to date documentation. Your API users will thank you.
Included is an example repository using these tools here: api_documentation_template.