Fully document the REST API using Swagger annotations

[DaoWen]

Our current REST API doc has some parts that are outdated or have always been inaccurate. We should fully document the REST API using the swagger annotations in the code. This would encourage/remind us to update the documentation when we make changes to the REST API.

We should also use defschema to get better JSON object names in the swagger data model descriptions. We're currently only doing this for the data on /info.^link

[rjseymour66]

I am a professional technical writer with REST API experience. Do you still need help on this?

[DaoWen]

@rjseymour66 - A pull request for this would be welcome. Are you familiar with Clojure and Swagger?

The changes described here would be made almost exclusively to the following source file:
https://github.com/twosigma/Cook/blob/master/scheduler/src/cook/mesos/api.clj

All new contributors also need to sign and submit the Contributor License Agreement before we can accept any changes or other contributions to this project:
https://github.com/twosigma/Cook/tree/master/cla