Auto-generated API documentation

Let's face it, you are probably not documenting as much as you should. However, code is read a lot more than it is written. We often think about the computer executing the code, but how often do you think about your fellow co-workers/co-programmers when writing your code?

Unfortunately, when you are a startup, you often simply can't do all the things that you should do. How great would it be if the code you already wrote would document itself?

While I can't quite offer you that level of magic yet, if you do write API tests, then hopefully you find rspec-api-blueprint-formatter useful. It will take something like this:

it 'retrievs the patients medications' do retrieve_medications expect(JSON.parse(response.body).length).to eql 1 expect(response).to have_http_status(:ok) end

and turns it into something like this:

(See the full demo here from the example app with RSpec tests)

What the gem does is add a custom formatter for RSpec that extracts metadata from the request that is being specified, as well as the response that is being asserted in the test. With some additional metadata as tags on the tests, we have everything to build a markdown document according to the APIBlueprint Format. That in turn allows us to use many of the tools of the ecosystem like Aglio that can generate a browsable HTML representation of our documentation.

Thus, if you have decent test coverage, especially with your various scenarious and edge cases, you will get real requests and real responses for your API consumers to read over. You will also get versioned API docs for free as your API docs are tied to your tests. Did I mention free? Check it out!