How to create the perfect REST API documentation #apicraft #api

Somehow I’m pretty pumped about the fact that I was able to just create a markdown file that describes my API (blueprint), adjust and run my integration tests driven by it (dredd), and once everything passed, simply ship it to my partners/users/contractors knowing that it will be a 100% up-to-date, readable and actionable documentation.

I’m also pretty sure that somehow, somewhere this totally breaks HATEOAS (of the “this ish documents itself” school of thought), and that maybe Swagger or something else might handle some use cases much better, but for now I’m just going to enjoy the fact that once the tests are done, I can just point all the parties involved to one file, followed, in full confidence, by the magic word – RTFM!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s