fix typing of api doc @model definitions

refs CNVS-26515

Pretty much anything that wasn't a number was being rendered as a
string, including sub-arrays and sub-objects. Worse, a lot of our api
docs were defining them using ruby syntax rather than json syntax.

This change fixes types so that booleans, arrays, and objects all render
correctly in the @model docs (the "A ModuleItem object looks like:"
sections of the docs). It also adds some basic error checking to help
avoid future mistakes.

This doesn't fully support the "$ref" OpenAPI (swagger) syntax yet, but
still renders examples for "$ref" fields when an example is provided.
Eventually it'd be nice to auto-generate an example for "$ref" fields,
since we can look at the linked documentation and just embed it.

test plan: generate the api documentation and look through the @model
definitions at the top of each Resources page. the new rendering should
show more accurate type information.

Change-Id: Id5af514cd235e66af2ce868bce95eb49d71062ab
Reviewed-on: https://gerrit.instructure.com/70484
Tested-by: Jenkins
Reviewed-by: Simon Williams <simon@instructure.com>
Product-Review: Brian Palmer <brianp@instructure.com>
QA-Review: Brian Palmer <brianp@instructure.com>

app/controllers/account_notifications_controller.rb

@@ -46,9 +46,8 @@
 #         },
 #         "icon": {
 #           "description": "The icon to display with the message.  Defaults to warning.",
-#           "example": "[\"information\"]",
-#           "type": "array",
-#           "items": {"type": "string"},
+#           "example": "information",
+#           "type": "string",
 #           "allowableValues": {
 #             "values": [
 #               "warning",
@@ -61,13 +60,13 @@
 #         },
 #         "roles": {
 #           "description": "(Deprecated) The roles to send the notification to.  If roles is not passed it defaults to all roles",
-#           "example": "[\"StudentEnrollment\"]",
+#           "example": ["StudentEnrollment"],
 #           "type": "array",
 #           "items": {"type": "string"}
 #         },
 #         "role_ids": {
 #           "description": "The roles to send the notification to.  If roles is not passed it defaults to all roles",
-#           "example": "[1]",
+#           "example": [1],
 #           "type": "array",
 #           "items": {"type": "integer"}
 #         }

app/controllers/account_reports_controller.rb

@@ -46,6 +46,7 @@
 #         },
 #         "parameters": {
 #           "description": "The report parameters",
+#           "example": {"course_id": 2, "start_at": "2012-07-13T10:55:20-06:00", "end_at": "2012-07-13T10:55:20-06:00"},
 #           "$ref": "ReportParameters"
 #         },
 #         "progress": {
@@ -141,10 +142,11 @@
 #           "example": false,
 #           "type": "boolean"
 #         },
-#         "enrollment_state[]": {
+#         "enrollment_state": {
 #           "description": "Include enrollment state. Defaults to 'all' Options: ['active'| 'invited'| 'creation_pending'| 'deleted'| 'rejected'| 'completed'| 'inactive'| 'all']",
-#           "example": "['all']",
-#           "type": "string"
+#           "example": ["all"],
+#           "type": "array",
+#           "items": {"type": "string"}
 #         },
 #         "start_at": {
 #           "description": "The beginning date for submissions. Max time range is 2 weeks.",

app/controllers/appointment_groups_controller.rb

@@ -93,19 +93,19 @@
 #         },
 #         "reserved_times": {
 #           "description": "The start and end times of slots reserved by the current user as well as the id of the calendar event for the reservation (see include[] argument)",
-#           "example": "[{\"id\"=>987, \"start_at\"=>\"2012-07-20T15:00:00-06:00\", \"end_at\"=>\"2012-07-20T15:00:00-06:00\"}]",
+#           "example": [{"id": 987, "start_at": "2012-07-20T15:00:00-06:00", "end_at": "2012-07-20T15:00:00-06:00"}],
 #           "type": "array",
 #           "items": {"$ref": "Appointment"}
 #         },
 #         "context_codes": {
 #           "description": "The context codes (i.e. courses) this appointment group belongs to. Only people in these courses will be eligible to sign up.",
-#           "example": "[course_123]",
+#           "example": ["course_123"],
 #           "type": "array",
 #           "items": {"type": "string"}
 #         },
 #         "sub_context_codes": {
 #           "description": "The sub-context codes (i.e. course sections and group categories) this appointment group is restricted to",
-#           "example": "[course_section_234]",
+#           "example": ["course_section_234"],
 #           "type": "array",
 #           "items": {"type": "integer"}
 #         },
@@ -133,13 +133,13 @@
 #         },
 #         "appointments": {
 #           "description": "Calendar Events representing the time slots (see include[] argument) Refer to the Calendar Events API for more information",
-#           "example": "[]",
+#           "example": [],
 #           "type": "array",
 #           "items": {"$ref": "CalendarEvent"}
 #         },
 #         "new_appointments": {
 #           "description": "Newly created time slots (same format as appointments above). Only returned in Create/Update responses where new time slots have been added",
-#           "example": "[]",
+#           "example": [],
 #           "type": "array",
 #           "items": {"$ref": "CalendarEvent"}
 #         },

app/controllers/assignment_groups_controller.rb

@@ -37,7 +37,7 @@
 #         },
 #         "never_drop": {
 #           "description": "Assignment IDs that should never be dropped.",
-#           "example": "[33, 17, 24]",
+#           "example": [33, 17, 24],
 #           "type": "array",
 #           "items": {"type": "integer"}
 #         }
@@ -70,7 +70,7 @@
 #         },
 #         "assignments": {
 #           "description": "the assignments in this Assignment Group (see the Assignment API for a detailed list of fields)",
-#           "example": "[]",
+#           "example": [],
 #           "type": "array",
 #           "items": {"type": "integer"}
 #         },

app/controllers/assignment_overrides_controller.rb

@@ -36,7 +36,7 @@
 #         },
 #         "student_ids": {
 #           "description": "the IDs of the override's target students (present if the override targets an ad-hoc set of students)",
-#           "example": "[1, 2, 3]",
+#           "example": [1, 2, 3],
 #           "type": "array",
 #           "items": {"type": "integer"}
 #         },

app/controllers/assignments_api_controller.rb

@@ -303,7 +303,7 @@
 #         },
 #         "allowed_extensions": {
 #           "description": "Allowed file extensions, which take effect if submission_types includes 'online_upload'.",
-#           "example": "[\"docx\", \"ppt\"]",
+#           "example": ["docx", "ppt"],
 #           "type": "array",
 #           "items": {"type": "string"}
 #         },
@@ -395,7 +395,7 @@
 #         },
 #         "submission_types": {
 #           "description": "the types of submissions allowed for this assignment list containing one or more of the following: 'discussion_topic', 'online_quiz', 'on_paper', 'none', 'external_tool', 'online_text_entry', 'online_url', 'online_upload' 'media_recording'",
-#           "example": "[\"online_text_entry\"]",
+#           "example": ["online_text_entry"],
 #           "type": "array",
 #           "items": {"type": "string"},
 #           "allowableValues": {
@@ -485,13 +485,12 @@
 #         },
 #         "frozen_attributes": {
 #           "description": "(Optional) Array of frozen attributes for the assignment. Only account administrators currently have permission to change an attribute in this list. Will be empty if no attributes are frozen for this assignment. Possible frozen attributes are: title, description, lock_at, points_possible, grading_type, submission_types, assignment_group_id, allowed_extensions, group_category_id, notify_of_update, peer_reviews NOTE: This field will only be present if the AssignmentFreezer plugin is available for your account.",
-#           "example": "[\"title\"]",
+#           "example": ["title"],
 #           "type": "array",
 #           "items": {"type": "string"}
 #         },
 #         "submission": {
 #           "description": "(Optional) If 'submission' is included in the 'include' parameter, includes a Submission object that represents the current user's (user who is requesting information from the api) current submission for the assignment. See the Submissions API for an example response. If the user does not have a submission, this key will be absent.",
-#           "example": "{}",
 #           "$ref": "Submission"
 #         },
 #         "use_rubric_for_grading": {
@@ -511,7 +510,7 @@
 #         },
 #         "assignment_visibility": {
 #           "description": "(Optional) If 'assignment_visibility' is included in the 'include' parameter, includes an array of student IDs who can see this assignment.",
-#           "example": "[137,381,572]",
+#           "example": [137,381,572],
 #           "type": "array",
 #           "items": {"type": "integer"}
 #         },

app/controllers/conferences_controller.rb

@@ -95,7 +95,7 @@
 #         },
 #         "users": {
 #           "description": "Array of user ids that are participants in the conference",
-#           "example": "[1, 7, 8, 9, 10]",
+#           "example": [1, 7, 8, 9, 10],
 #           "type": "array",
 #           "items": { "type": "integer"}
 #         },
@@ -111,10 +111,8 @@
 #         },
 #         "user_settings": {
 #           "description": "A collection of settings specific to the conference type",
-#           "example": "{}",
-#           "type": "map",
-#           "key": { "type": "string" },
-#           "value": { "type": "string" }
+#           "example": {"record": true},
+#           "type": "object"
 #         },
 #         "recordings": {
 #           "description": "A List of recordings for the conference",

app/controllers/content_exports_api_controller.rb

@@ -49,7 +49,7 @@
 #         },
 #         "attachment": {
 #           "description": "attachment api object for the export package (not present until the export completes)",
-#           "example": "{\"url\"=>\"https://example.com/api/v1/attachments/789?download_frd=1&verifier=bG9sY2F0cyEh\"}",
+#           "example": {"url": "https://example.com/api/v1/attachments/789?download_frd=1&verifier=bG9sY2F0cyEh"},
 #           "$ref": "File"
 #         },
 #         "progress_url": {

app/controllers/content_migrations_controller.rb

@@ -114,7 +114,7 @@
 #         },
 #         "required_settings": {
 #           "description": "A list of fields this system requires",
-#           "example": "\[\]",
+#           "example": ["source_course_id"],
 #           "type": "array",
 #           "items": {"type": "string"}
 #         }

app/controllers/context_module_items_api_controller.rb

@@ -165,12 +165,12 @@
 #         },
 #         "completion_requirement": {
 #           "description": "Completion requirement for this module item",
-#           "example": "{\"type\"=>\"min_score\", \"min_score\"=>10, \"completed\"=>true}",
+#           "example": {"type": "min_score", "min_score": 10, "completed": true},
 #           "$ref": "CompletionRequirement"
 #         },
 #         "content_details": {
 #           "description": "(Present only if requested through include[]=content_details) If applicable, returns additional details specific to the associated object",
-#           "example": "{\"points_possible\"=>20, \"due_at\"=>\"2012-12-31T06:00:00-06:00\", \"unlock_at\"=>\"2012-12-31T06:00:00-06:00\", \"lock_at\"=>\"2012-12-31T06:00:00-06:00\"}",
+#           "example": {"points_possible": 20, "due_at": "2012-12-31T06:00:00-06:00", "unlock_at": "2012-12-31T06:00:00-06:00", "lock_at": "2012-12-31T06:00:00-06:00"},
 #           "$ref": "ContentDetails"
 #         }
 #       }
@@ -183,8 +183,9 @@
 #       "properties": {
 #         "items": {
 #           "description": "an array containing one hash for each appearence of the asset in the module sequence (up to 10 total)",
-#           "example": "[{\"prev\"=>nil, \"current\"=>{\"id\"=>768, \"module_id\"=>123, \"title\"=>\"A lonely page\", \"type\"=>\"Page\"}, \"next\"=>{\"id\"=>769, \"module_id\"=>127, \"title\"=>\"Project 1\", \"type\"=>\"Assignment\"}}]",
-#           "type": "string"
+#           "example": [{"prev": null, "current": {"id": 768, "module_id": 123, "title": "A lonely page", "type": "Page"}, "next": {"id": 769, "module_id": 127, "title": "Project 1", "type": "Assignment"}}],
+#           "type": "array",
+#           "items": { "type": "object" }
 #         },
 #         "modules": {
 #           "description": "an array containing each Module referenced above",

app/controllers/context_modules_api_controller.rb

@@ -271,7 +271,7 @@
 #         },
 #         "prerequisite_module_ids": {
 #           "description": "IDs of Modules that must be completed before this one is unlocked",
-#           "example": "\[121, 122\]",
+#           "example": [121, 122],
 #           "type": "array",
 #           "items": {"type": "integer"}
 #         },
@@ -287,7 +287,6 @@
 #         },
 #         "items": {
 #           "description": "The contents of this module, as an array of Module Items. (Present only if requested via include[]=items AND the module is not deemed too large by Canvas.)",
-#           "example": "\[\]",
 #           "type": "array",
 #           "items": { "$ref": "ModuleItem" }
 #         },

app/controllers/course_audit_api_controller.rb

@@ -103,7 +103,7 @@
 #         },
 #         "links": {
 #           "description": "Jsonapi.org links",
-#           "example": "{\"course\"=>\"12345\", \"user\"=>\"12345\", \"page_view\"=>\"e2b76430-27a5-0131-3ca1-48e0eb13f29b\"}",
+#           "example": {"course": "12345", "user": "12345", "page_view": "e2b76430-27a5-0131-3ca1-48e0eb13f29b"},
 #           "$ref": "CourseEventLink"
 #         }
 #       }
@@ -115,22 +115,22 @@
 #       "description": "The created event data object returns all the fields that were set in the format of the following example.  If a field does not exist it was not set. The value of each field changed is in the format of [:old_value, :new_value].  The created event type also includes a created_source field to specify what triggered the creation of the course.",
 #       "properties": {
 #         "name": {
-#           "example": "[nil, \"Course 1\"]",
+#           "example": [null, "Course 1"],
 #           "type": "array",
 #           "items": { "type": "string" }
 #         },
 #         "start_at": {
-#           "example": "[nil, \"2012-01-19T15:00:00-06:00\"]",
+#           "example": [null, "2012-01-19T15:00:00-06:00"],
 #           "type": "array",
 #           "items": { "type": "datetime" }
 #         },
 #         "conclude_at": {
-#           "example": "[nil, \"2012-01-19T15:00:00-08:00\"]",
+#           "example": [null, "2012-01-19T15:00:00-08:00"],
 #           "type": "array",
 #           "items": { "type": "datetime" }
 #         },
 #         "is_public": {
-#           "example": "[nil, false]",
+#           "example": [null, false],
 #           "type": "array",
 #           "items": { "type": "boolean" }
 #         },
@@ -144,22 +144,22 @@
 #       "description": "The updated event data object returns all the fields that have changed in the format of the following example.  If a field does not exist it was not changed.  The value is an array that contains the before and after values for the change as in [:old_value, :new_value].",
 #       "properties": {
 #         "name": {
-#           "example": "[\"Course 1\", \"Course 2\"]",
+#           "example": ["Course 1", "Course 2"],
 #           "type": "array",
 #           "items": { "type": "string" }
 #         },
 #         "start_at": {
-#           "example": "[\"2012-01-19T15:00:00-06:00\", \"2012-07-19T15:00:00-06:00\"]",
+#           "example": ["2012-01-19T15:00:00-06:00", "2012-07-19T15:00:00-06:00"],
 #           "type": "array",
 #           "items": { "type": "datetime" }
 #         },
 #         "conclude_at": {
-#           "example": "[\"2012-01-19T15:00:00-08:00\", \"2012-07-19T15:00:00-08:00\"]",
+#           "example": ["2012-01-19T15:00:00-08:00", "2012-07-19T15:00:00-08:00"],
 #           "type": "array",
 #           "items": { "type": "datetime" }
 #         },
 #         "is_public": {
-#           "example": "[true, false]",
+#           "example": [true, false],
 #           "type": "array",
 #           "items": { "type": "boolean" }
 #         }

app/controllers/courses_controller.rb

@@ -198,8 +198,8 @@
 #         },
 #         "permissions": {
 #           "description": "optional: the permissions the user has for the course. returned only for a single course and include[]=permissions",
-#           "example": "{\"create_discussion_topic\"=>true,\"create_announcement\"=>true}",
-#           "type": "map",
+#           "example": {"create_discussion_topic": true, "create_announcement": true},
+#           "type": "object",
 #           "key": { "type": "string" },
 #           "value": { "type": "boolean" }
 #         },
@@ -225,7 +225,7 @@
 #         },
 #         "storage_quota_used_mb": {
 #           "example": 5,
-#           "type": "float"
+#           "type": "number"
 #         },
 #         "hide_final_grades": {
 #           "example": false,

app/controllers/discussion_topics_controller.rb

@@ -177,7 +177,7 @@
 #         },
 #         "topic_children": {
 #           "description": "An array of topic_ids for the group discussions the user is a part of.",
-#           "example": "[5, 7, 10]",
+#           "example": [5, 7, 10],
 #           "type": "array",
 #           "items": { "type": "integer"}
 #         },
@@ -212,8 +212,8 @@
 #         },
 #         "permissions": {
 #           "description": "The current user's permissions on this topic.",
-#           "example": "{\"attach\"=>true}",
-#           "type": "map",
+#           "example": {"attach": true},
+#           "type": "object",
 #           "key": { "type": "string" },
 #           "value": { "type": "boolean" }
 #         },

app/controllers/epub_exports_controller.rb

@@ -60,7 +60,7 @@
 #         },
 #         "attachment": {
 #           "description": "attachment api object for the export ePub (not present until the export completes)",
-#           "example": "{\"url\"=>\"https://example.com/api/v1/attachments/789?download_frd=1&verifier=bG9sY2F0cyEh\"}",
+#           "example": {"url": "https://example.com/api/v1/attachments/789?download_frd=1&verifier=bG9sY2F0cyEh"},
 #           "$ref": "File"
 #         },
 #         "progress_url": {

app/controllers/feature_flags_controller.rb

@@ -54,7 +54,7 @@
 #         },
 #         "feature_flag": {
 #           "description": "The FeatureFlag that applies to the caller",
-#           "example": "\{\"feature\"=>\"fancy_wickets\", \"state\"=>\"allowed\", \"locking_account_id\"=>nil\}",
+#           "example": {"feature": "fancy_wickets", "state": "allowed", "locking_account_id": null},
 #           "$ref": "FeatureFlag"
 #         },
 #         "root_opt_in": {

app/controllers/gradebook_history_api_controller.rb

@@ -40,7 +40,7 @@
 #         },
 #         "assignments": {
 #           "description": "the assignment groups for all submissions in this response that were graded by this user.  The details are not nested inside here, but the fact that an assignment is present here means that the grader did grade submissions for this assignment on the contextual date. You can use the id of a grader and of an assignment to make another API call to find all submissions for a grader/assignment combination on a given date.",
-#           "example": "[]",
+#           "example": [1,2,3],
 #           "type": "array",
 #           "items": {"type": "integer"}
 #         }
@@ -199,9 +199,8 @@
 #         },
 #         "versions": {
 #           "description": "an array of all the versions of this submission",
-#           "example": "[]",
 #           "type": "array",
-#           "items": {"type": "integer"}
+#           "items": {"$ref": "SubmissionVersion"}
 #         }
 #       }
 #     }

app/controllers/grading_standards_api_controller.rb

@@ -63,7 +63,7 @@
 #         },
 #         "grading_scheme": {
 #           "description": "A list of GradingSchemeEntry that make up the Grading Standard as an array of values with the scheme name and value",
-#           "example": "[{\"name\":\"A\", \"value\":0.9}, {\"name\":\"B\", \"value\":0.8}, {\"name\":\"C\", \"value\":0.7}, {\"name\":\"D\", \"value\":0.6}]",
+#           "example": [{"name":"A", "value":0.9}, {"name":"B", "value":0.8}, {"name":"C", "value":0.7}, {"name":"D", "value":0.6}],
 #           "type": "array",
 #           "items": {"$ref": "GradingSchemeEntry"}
 #         }
@@ -175,4 +175,4 @@ def build_grading_scheme(params)
     end
     grading_standard_params
   end
-end
+end