self documenting apis


https://github.com/wordnik/swagger-spec
http://www.mashery.com/product/io-docs
http://apiary.io/blueprint