Hi @burke
Yes.I am going though the swagger documentation which was introduced by this project [Improved REST API Documentation Project - Midterm - Demo](http://GSoC Project For API documentation)
I think we can improve the swagger documentation as well with more proper responses errors and also describing more about the attributes in the api calls.
I already worked on similar project and done swagger documentations as well.
And also as in the github api documentation we can host the api documentation with all method based api documentation as well.