Document your Rails API by Writing Acceptance Specs

So you have been working on a Rails API, and now you need to create a browsable HTML documentation for it. One popular approach is to generate the docs from comments in the code. The problem with this is that comments are often not updated together with the code, and the documentation quickly becomes outdated. Recently I have started using an interesting alternative: Rspec Api Documentation.