Thx Lorna for sharing. I agree on most of your points an I experienced the same. We are using Apiary. Have you used that too? What I like about using it is that it already creates a test url to use it just from the docs. This makes it easy for our FE guys to start early.
One downside I’ve seen is obvious. Writing docs is not the same as building the api. I ran into several occasions where I needed to change something because it didn’t work out as I aspected it. These changes are not that easy. But guess is the price you get. Still better than the other approaches. Cheers