The one shortcoming of these approaches is that they are well-suited for local APIs but less so for network APIs, especially as you start to wire them together. For example, with network APIs you need to worry about stuff like rate limiting, and there's no way to express them.

That said, if you're trying to document a bunch of REST APIs, it's a very helpful thing to do. Just not a total solution :)