Tag Archives: api

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!