converting @object notation to @model - Part 2/11

Contributed by github.com/mcgachey

  app/controllers/assignment_groups_controller.rb
  app/controllers/assignment_overrides_controller.rb
  app/controllers/assignments_api_controller.rb
  app/controllers/authentication_audit_api_controller.rb
  app/controllers/calendar_events_api_controller.rb

Fixes SIS-146

Currently, some API objects are documented using the @object tag, and
others are documented using @model. The @model tag is preferred because
it provides more information in the machine-readable Swagger documents
generated by the API documentation build step. For example, the @object
notation does not give a way to specify that a model property contains
an instance of another type. This complete information is necessary in
order to build an SDK generator.

This change converts the @object notations into @model, adding missing
type information and correcting inaccurate data (for example, dates were
typed as "string" in the existing JSON documentation). Embedded types are
also separated out so that their format can also be documented - this
information was previously lost.

The change also makes two minor fixes to the HTML and JSON documentation
generators. The HTML generator is fixed so that a missing documentation
string is ignored rather than being shown as an empty comment, and the
JSON generator is modified so that the Model-level documentation and
required attributes are properly provided.

Note that the JSON generated here is not fully-complient to the Swagger
format. Swagger does not support a Map structure, but the Canvas API
uses (semi-)arbitrary key/value dictionaries in a few places. In those
instances the properties are typed as "map", but this is not a part of the
Swagger spec. Any cleaner alternative approaches here would be welcome.

Change-Id: I450539cb5311778038c6179dd46ec06aa6c71791
Reviewed-on: https://gerrit.instructure.com/29995
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Rob Orton <rob@instructure.com>
Product-Review: Rob Orton <rob@instructure.com>
QA-Review: Rob Orton <rob@instructure.com>