Isn't this how waterfall development was/is supposed to work.
If you have separate teams designing the client and server, you'll eventually get to a point where you need to agree on the messages passed.
We use it to document services by reflecting docs off of the implemented service. Upside, no drift!
Here's an API document I wrote. Comments?
You asked, so:
The organization can be better. Usually when I am looking at an API, the first question I have is, "What is this API, what can I do with it?" There's one sentence about that in the header, but it's not very clear. Then you jump right into low-level protocol details. Your pictures are good, and help to understand, but they come way late.
The broad organization should be something like: 1 "Here's what you can do with this API" 2 "Here's how to use it" 3 "Here are the fine details" and maybe (4 "Legal garbage")
Nice quote at the bottom.