instructure/canvas-lms — pull request #396 by mcgachey (2014-01-30 16:10:45+00:00)
Title: Convert API documentation @object notation to @model

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), and enumeration-type strings are explicitly documented with their allowable values.

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 compliant 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.

This change is the first (and hopefully the most disruptive) of a series of changes that aim to make the Canvas API specification machine-consumable, with the end goal of building an automatic SDK generator. The JSON model specifications that the build process generates after this change have been successfully converted into type-correct Java files. Later work will first verify that the parameter and return specifications of the various API methods are correct, and then that the models in the specification exactly correspond to the data returned by the Canvas server.