People who design APIs. I am begging you. It doesn't matter how "simple" or "intuitive" or "elegant" your API is. You need to include sample code.
@clacke @mcc @foobarsoft I've always preferred swagger interfaces if they are done well
@bassplayer They can be done well, with excellent examples and guidance and all, but they can also be just a list of endpoints, and depending on the backend the spec may or may not match the implementation.
@bassplayer In principle I agree with you, and I think a form of executable documentation is the best documentation. An excellent Swagger UI is a great troubleshooting and teaching tool.
But there's no guarantee, and it's easy to say "documentation? oh yeah we have a swagger", which may be glorious or it may mean almost nothing.