Improve Resource Definition Documentation

Right now, we we only document full representations and have completely separate definitions in the Swagger spec for GET and POST objects. Also, all datatypes are string. We should improve things by using better schema objects that include the correct data type.

Having some examples in the docs also wouldn't hurt.

Approach taken to implement as discussed in the talk thread:

• Use swagger-core library as a helper library. This prevents us from having to maintain our own set of swagger model classes.
• Introuduces three new methods, which are used to document resource classes.
  • getGETModel(Representation) : returns a object representing GET representation schema of the resource
  • getCREATEModel(Representation) : returns a object representing CREATE representation schema of the resource
  • getUPDATEModel(Representation) : returns a object representing POST Update representation schema of the resource

A resource should implement these methods in order for it to be appear on the swagger doc, though it is not mandatory.