I 've been in the trenches the past 1.5 weeks doing API documentation. This was Dakota's big idea, which has turned out to be an excellent one.
The SIGKATA API provides a metadata structure for our app model at sigkat.com/services/api/model. Metadata for individual classes in the model can be accessed at sigkat.com/api/model/<class name>, for example, sigkat.com/services/api/model/CredentialType.
We generate all our class and other structures specs from this metadata as well as many of our UI components, editing dialogs being an obvious example.
Doing the documentation this way helped us straighten out some issues in the model metadata. Eventually, we will expand this facility such that sigkat.com/services/api will return a metadata structure for non-model api resources, but we haven't gotten to this yet largely because we don't have much in the way of non-model api resources yet.