I absolutely agree with that. But you could take that to the next level. E.g. If you need to document REST interfaces, you could just write a document, wiki page or whatever. But that's similar to writing code comments. You could use some annotation based documenting framework, but you're still able to annotate any response code that does not have to match.
So we wrote a litte tool that captures requests, responses and additional textual information during test execution.
You're forced to have at least one test covering each use case and when all tests are green, you've got an up to date REST documentation as markdown.
We’re a place where coders share, stay up-to-date and grow their careers.
We strive for transparency and don't collect excess data.