ylqjgm
/
canvas-lms
mirror of https://github.com/instructure/canvas-lms.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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>
This commit is contained in:
Brian Palmer 2016-01-18 11:22:23 -07:00
parent 73e1c32fff
commit 933a052061
28 changed files with 103 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
app/controllers/account_notifications_controller.rb
View File

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

8
app/controllers/account_reports_controller.rb
View File

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

10
app/controllers/appointment_groups_controller.rb
View File

@ -93,19 +93,19 @@
# }, # },
# "reserved_times": { # "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)", # "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", # "type": "array",
# "items": {"$ref": "Appointment"} # "items": {"$ref": "Appointment"}
# }, # },
# "context_codes": { # "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.", # "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", # "type": "array",
# "items": {"type": "string"} # "items": {"type": "string"}
# }, # },
# "sub_context_codes": { # "sub_context_codes": {
# "description": "The sub-context codes (i.e. course sections and group categories) this appointment group is restricted to", # "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", # "type": "array",
# "items": {"type": "integer"} # "items": {"type": "integer"}
# }, # },
@ -133,13 +133,13 @@
# }, # },
# "appointments": { # "appointments": {
# "description": "Calendar Events representing the time slots (see include[] argument) Refer to the Calendar Events API for more information", # "description": "Calendar Events representing the time slots (see include[] argument) Refer to the Calendar Events API for more information",
# "example": "[]", # "example": [],
# "type": "array", # "type": "array",
# "items": {"$ref": "CalendarEvent"} # "items": {"$ref": "CalendarEvent"}
# }, # },
# "new_appointments": { # "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", # "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", # "type": "array",
# "items": {"$ref": "CalendarEvent"} # "items": {"$ref": "CalendarEvent"}
# }, # },

4
app/controllers/assignment_groups_controller.rb
View File

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

2
app/controllers/assignment_overrides_controller.rb
View File

@ -36,7 +36,7 @@
# }, # },
# "student_ids": { # "student_ids": {
# "description": "the IDs of the override's target students (present if the override targets an ad-hoc set of students)", # "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", # "type": "array",
# "items": {"type": "integer"} # "items": {"type": "integer"}
# }, # },

9
app/controllers/assignments_api_controller.rb
View File

@ -303,7 +303,7 @@
# }, # },
# "allowed_extensions": { # "allowed_extensions": {
# "description": "Allowed file extensions, which take effect if submission_types includes 'online_upload'.", # "description": "Allowed file extensions, which take effect if submission_types includes 'online_upload'.",
# "example": "[\"docx\", \"ppt\"]", # "example": ["docx", "ppt"],
# "type": "array", # "type": "array",
# "items": {"type": "string"} # "items": {"type": "string"}
# }, # },
@ -395,7 +395,7 @@
# }, # },
# "submission_types": { # "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'", # "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", # "type": "array",
# "items": {"type": "string"}, # "items": {"type": "string"},
# "allowableValues": { # "allowableValues": {
@ -485,13 +485,12 @@
# }, # },
# "frozen_attributes": { # "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.", # "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", # "type": "array",
# "items": {"type": "string"} # "items": {"type": "string"}
# }, # },
# "submission": { # "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.", # "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" # "$ref": "Submission"
# }, # },
# "use_rubric_for_grading": { # "use_rubric_for_grading": {
@ -511,7 +510,7 @@
# }, # },
# "assignment_visibility": { # "assignment_visibility": {
# "description": "(Optional) If 'assignment_visibility' is included in the 'include' parameter, includes an array of student IDs who can see this assignment.", # "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", # "type": "array",
# "items": {"type": "integer"} # "items": {"type": "integer"}
# }, # },

8
app/controllers/conferences_controller.rb
View File

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

2
app/controllers/content_exports_api_controller.rb
View File

@ -49,7 +49,7 @@
# }, # },
# "attachment": { # "attachment": {
# "description": "attachment api object for the export package (not present until the export completes)", # "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" # "$ref": "File"
# }, # },
# "progress_url": { # "progress_url": {

2
app/controllers/content_migrations_controller.rb
View File

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

9
app/controllers/context_module_items_api_controller.rb
View File

@ -165,12 +165,12 @@
# }, # },
# "completion_requirement": { # "completion_requirement": {
# "description": "Completion requirement for this module item", # "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" # "$ref": "CompletionRequirement"
# }, # },
# "content_details": { # "content_details": {
# "description": "(Present only if requested through include[]=content_details) If applicable, returns additional details specific to the associated object", # "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" # "$ref": "ContentDetails"
# } # }
# } # }
@ -183,8 +183,9 @@
# "properties": { # "properties": {
# "items": { # "items": {
# "description": "an array containing one hash for each appearence of the asset in the module sequence (up to 10 total)", # "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\"}}]", # "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": "string" # "type": "array",
# "items": { "type": "object" }
# }, # },
# "modules": { # "modules": {
# "description": "an array containing each Module referenced above", # "description": "an array containing each Module referenced above",

3
app/controllers/context_modules_api_controller.rb
View File

@ -271,7 +271,7 @@
# }, # },
# "prerequisite_module_ids": { # "prerequisite_module_ids": {
# "description": "IDs of Modules that must be completed before this one is unlocked", # "description": "IDs of Modules that must be completed before this one is unlocked",
# "example": "\[121, 122\]", # "example": [121, 122],
# "type": "array", # "type": "array",
# "items": {"type": "integer"} # "items": {"type": "integer"}
# }, # },
@ -287,7 +287,6 @@
# }, # },
# "items": { # "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.)", # "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", # "type": "array",
# "items": { "$ref": "ModuleItem" } # "items": { "$ref": "ModuleItem" }
# }, # },

18
app/controllers/course_audit_api_controller.rb
View File

@ -103,7 +103,7 @@
# }, # },
# "links": { # "links": {
# "description": "Jsonapi.org 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" # "$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.", # "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": { # "properties": {
# "name": { # "name": {
# "example": "[nil, \"Course 1\"]", # "example": [null, "Course 1"],
# "type": "array", # "type": "array",
# "items": { "type": "string" } # "items": { "type": "string" }
# }, # },
# "start_at": { # "start_at": {
# "example": "[nil, \"2012-01-19T15:00:00-06:00\"]", # "example": [null, "2012-01-19T15:00:00-06:00"],
# "type": "array", # "type": "array",
# "items": { "type": "datetime" } # "items": { "type": "datetime" }
# }, # },
# "conclude_at": { # "conclude_at": {
# "example": "[nil, \"2012-01-19T15:00:00-08:00\"]", # "example": [null, "2012-01-19T15:00:00-08:00"],
# "type": "array", # "type": "array",
# "items": { "type": "datetime" } # "items": { "type": "datetime" }
# }, # },
# "is_public": { # "is_public": {
# "example": "[nil, false]", # "example": [null, false],
# "type": "array", # "type": "array",
# "items": { "type": "boolean" } # "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].", # "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": { # "properties": {
# "name": { # "name": {
# "example": "[\"Course 1\", \"Course 2\"]", # "example": ["Course 1", "Course 2"],
# "type": "array", # "type": "array",
# "items": { "type": "string" } # "items": { "type": "string" }
# }, # },
# "start_at": { # "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", # "type": "array",
# "items": { "type": "datetime" } # "items": { "type": "datetime" }
# }, # },
# "conclude_at": { # "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", # "type": "array",
# "items": { "type": "datetime" } # "items": { "type": "datetime" }
# }, # },
# "is_public": { # "is_public": {
# "example": "[true, false]", # "example": [true, false],
# "type": "array", # "type": "array",
# "items": { "type": "boolean" } # "items": { "type": "boolean" }
# } # }

6
app/controllers/courses_controller.rb
View File

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

6
app/controllers/discussion_topics_controller.rb
View File

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

2
app/controllers/epub_exports_controller.rb
View File

@ -60,7 +60,7 @@
# }, # },
# "attachment": { # "attachment": {
# "description": "attachment api object for the export ePub (not present until the export completes)", # "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" # "$ref": "File"
# }, # },
# "progress_url": { # "progress_url": {

2
app/controllers/feature_flags_controller.rb
View File

@ -54,7 +54,7 @@
# }, # },
# "feature_flag": { # "feature_flag": {
# "description": "The FeatureFlag that applies to the caller", # "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" # "$ref": "FeatureFlag"
# }, # },
# "root_opt_in": { # "root_opt_in": {

5
app/controllers/gradebook_history_api_controller.rb
View File

@ -40,7 +40,7 @@
# }, # },
# "assignments": { # "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.", # "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", # "type": "array",
# "items": {"type": "integer"} # "items": {"type": "integer"}
# } # }
@ -199,9 +199,8 @@
# }, # },
# "versions": { # "versions": {
# "description": "an array of all the versions of this submission", # "description": "an array of all the versions of this submission",
# "example": "[]",
# "type": "array", # "type": "array",
# "items": {"type": "integer"} # "items": {"$ref": "SubmissionVersion"}
# } # }
# } # }
# } # }

4
app/controllers/grading_standards_api_controller.rb
View File

@ -63,7 +63,7 @@
# }, # },
# "grading_scheme": { # "grading_scheme": {
# "description": "A list of GradingSchemeEntry that make up the Grading Standard as an array of values with the scheme name and value", # "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", # "type": "array",
# "items": {"$ref": "GradingSchemeEntry"} # "items": {"$ref": "GradingSchemeEntry"}
# } # }
@ -175,4 +175,4 @@ class GradingStandardsApiController < ApplicationController
end end
grading_standard_params grading_standard_params
end end
end end

4
app/controllers/groups_controller.rb
View File

@ -125,8 +125,8 @@ require 'atom'
# }, # },
# "permissions": { # "permissions": {
# "description": "optional: the permissions the user has for the group. returned only for a single group and include[]=permissions", # "description": "optional: the permissions the user has for the group. returned only for a single group and include[]=permissions",
# "example": "{\"create_discussion_topic\"=>true,\"create_announcement\"=>true}", # "example": {"create_discussion_topic": true, "create_announcement": true},
# "type": "map", # "type": "object",
# "key": { "type": "string" }, # "key": { "type": "string" },
# "value": { "type": "boolean" } # "value": { "type": "boolean" }
# } # }

2
app/controllers/live_assessments/results_controller.rb
View File

@ -42,7 +42,7 @@ module LiveAssessments
# "description": "When this result was recorded" # "description": "When this result was recorded"
# }, # },
# "links": { # "links": {
# "type": "ResultLinks", # "$ref": "ResultLinks",
# "example": {"user": "42", "assessor": "23", "assessment": "5"}, # "example": {"user": "42", "assessor": "23", "assessment": "5"},
# "description": "Unique identifiers of objects associated with this result" # "description": "Unique identifiers of objects associated with this result"
# } # }

7
app/controllers/outcome_results_controller.rb
View File

@ -42,7 +42,8 @@
# "type": "datetime" # "type": "datetime"
# }, # },
# "links": { # "links": {
# "example": "{\"user\"=>\"3\", \"learning_outcome\"=>\"97\", \"alignment\"=>\"53\"}", # "example": {"user": "3", "learning_outcome": "97", "alignment": "53"},
# "type": "object",
# "description": "Unique identifiers of objects associated with this result" # "description": "Unique identifiers of objects associated with this result"
# } # }
# } # }
@ -77,7 +78,7 @@
# "description": "The number of alignment scores included in this rollup." # "description": "The number of alignment scores included in this rollup."
# }, # },
# "links": { # "links": {
# "example": "{\"outcome\"=>\"42\"}", # "example": {"outcome": "42"},
# "$ref": "OutcomeRollupScoreLinks" # "$ref": "OutcomeRollupScoreLinks"
# } # }
# } # }
@ -121,7 +122,7 @@
# "type": "string" # "type": "string"
# }, # },
# "links": { # "links": {
# "example": "{\"course\"=>42, \"user\"=>42, \"section\"=>57}", # "example": {"course": 42, "user": 42, "section": 57},
# "$ref": "OutcomeRollupLinks" # "$ref": "OutcomeRollupLinks"
# } # }
# } # }

8
app/controllers/page_views_controller.rb
View File

@ -64,7 +64,7 @@
# "interaction_seconds": { # "interaction_seconds": {
# "description": "An approximation of how long the user spent on the page, in seconds", # "description": "An approximation of how long the user spent on the page, in seconds",
# "example": "7.21", # "example": "7.21",
# "type": "float" # "type": "number"
# }, # },
# "created_at": { # "created_at": {
# "description": "When the request was made", # "description": "When the request was made",
@ -80,7 +80,7 @@
# "render_time": { # "render_time": {
# "description": "How long the response took to render, in seconds", # "description": "How long the response took to render, in seconds",
# "example": "0.369", # "example": "0.369",
# "type": "float" # "type": "number"
# }, # },
# "user_agent": { # "user_agent": {
# "description": "The user-agent of the browser or program that made the request", # "description": "The user-agent of the browser or program that made the request",
@ -104,8 +104,8 @@
# }, # },
# "links": { # "links": {
# "description": "The page view links to define the relationships", # "description": "The page view links to define the relationships",
# "type": "PageViewLinks", # "$ref": "PageViewLinks",
# "example": "{}" # "example": {"user": 1234, "account": 1234}
# } # }
# } # }
# } # }

2
app/controllers/quizzes/quiz_questions_controller.rb
View File

@ -152,7 +152,7 @@
# "approximate": { # "approximate": {
# "description": "Used in numerical questions of type 'precision_answer'. The value the answer should equal.", # "description": "Used in numerical questions of type 'precision_answer'. The value the answer should equal.",
# "example": 1.2346e+9, # "example": 1.2346e+9,
# "type": "float", # "type": "number",
# "format": "float64" # "format": "float64"
# }, # },
# "precision": { # "precision": {

3
app/controllers/quizzes/quizzes_api_controller.rb
View File

@ -227,7 +227,8 @@
# "question_types": { # "question_types": {
# "description": "List of question types in the quiz", # "description": "List of question types in the quiz",
# "example": ["mutliple_choice", "essay"], # "example": ["mutliple_choice", "essay"],
# "type": "array" # "type": "array",
# "items": {"type": "string"}
# } # }
# } # }
# } # }

9
app/controllers/role_overrides_controller.rb
View File

@ -54,7 +54,7 @@
# #
# @model Role # @model Role
# { # {
# "id": 1, # "id": "Role",
# "description": "", # "description": "",
# "properties": { # "properties": {
# "label": { # "label": {
@ -74,7 +74,8 @@
# }, # },
# "account": { # "account": {
# "description": "JSON representation of the account the role is in.", # "description": "JSON representation of the account the role is in.",
# "example": "{\"id\"=>1019, \"name\"=>\"CGNU\", \"parent_account_id\"=>73, \"root_account_id\"=>1, \"sis_account_id\"=>\"cgnu\"}", # "example": {"id": 1019, "name": "CGNU", "parent_account_id": 73, "root_account_id": 1, "sis_account_id": "cgnu"},
# "type": "object",
# "$ref": "Account" # "$ref": "Account"
# }, # },
# "workflow_state": { # "workflow_state": {
@ -84,8 +85,8 @@
# }, # },
# "permissions": { # "permissions": {
# "description": "A dictionary of permissions keyed by name (see permissions input parameter in the 'Create a role' API).", # "description": "A dictionary of permissions keyed by name (see permissions input parameter in the 'Create a role' API).",
# "example": "{\"read_course_content\"=>{\"enabled\"=>true, \"locked\"=>false, \"readonly\"=>false, \"explicit\"=>true, \"prior_default\"=>false}, \"read_course_list\"=>{\"enabled\"=>true, \"locked\"=>true, \"readonly\"=>true, \"explicit\"=>false}, \"read_question_banks\"=>{\"enabled\"=>false, \"locked\"=>true, \"readonly\"=>false, \"explicit\"=>true, \"prior_default\"=>false}, \"read_reports\"=>{\"enabled\"=>true, \"locked\"=>false, \"readonly\"=>false, \"explicit\"=>false}}", # "example": {"read_course_content": {"enabled": true, "locked": false, "readonly": false, "explicit": true, "prior_default": false}, "read_course_list": {"enabled": true, "locked": true, "readonly": true, "explicit": false}, "read_question_banks": {"enabled": false, "locked": true, "readonly": false, "explicit": true, "prior_default": false}, "read_reports": {"enabled": true, "locked": false, "readonly": false, "explicit": false}},
# "type": "map", # "type": "object",
# "key": { "type": "string" }, # "key": { "type": "string" },
# "value": { "$ref": "RolePermissions" } # "value": { "$ref": "RolePermissions" }
# } # }

10
app/controllers/sis_imports_api_controller.rb
View File

@ -145,18 +145,20 @@
# }, # },
# "processing_warnings": { # "processing_warnings": {
# "description": "Only imports that are complete will get this data. An array of CSV_file/warning_message pairs.", # "description": "Only imports that are complete will get this data. An array of CSV_file/warning_message pairs.",
# "example": "[['students.csv','user John Doe has already claimed john_doe's requested login information, skipping'], ...]", # "example": [["students.csv","user John Doe has already claimed john_doe's requested login information, skipping"]],
# "type": "array", # "type": "array",
# "items": { # "items": {
# "type": "string" # "type": "array",
# "items": {"type": "string"}
# } # }
# }, # },
# "processing_errors": { # "processing_errors": {
# "description": "An array of CSV_file/error_message pairs.", # "description": "An array of CSV_file/error_message pairs.",
# "example": "[['students.csv','Error while importing CSV. Please contact support.'], ...]", # "example": [["students.csv","Error while importing CSV. Please contact support."]],
# "type": "array", # "type": "array",
# "items": { # "items": {
# "type": "string" # "type": "array",
# "items": {"type": "string"}
# } # }
# }, # },
# "batch_mode": { # "batch_mode": {

2
app/controllers/submissions_api_controller.rb
View File

@ -79,7 +79,7 @@
# "score": { # "score": {
# "description": "The raw score", # "description": "The raw score",
# "example": 13.5, # "example": 13.5,
# "type": "float" # "type": "number"
# }, # },
# "submission_comments": { # "submission_comments": {
# "description": "Associated comments for a submission (optional)", # "description": "Associated comments for a submission (optional)",

29
doc/api/topic/html/setup.rb
View File

@ -66,10 +66,26 @@ def render_comment(string, wrap = 75)
end end
end end
def render_value(value, type = 'string') def render_value(prop)
case type value = prop['example']
when 'integer', 'number' then value.to_s
else %{"#{value}"} return "null" if value.nil?
if prop['$ref']
# we don't fully support $refs yet in these generated docs, but some of our
# docs include an example sub-object so let's at least render that
return JSON.generate(value)
end
case prop['type']
when 'array'
"[#{value.map { |v| render_value(prop['items'].merge('example' => v)) }.join(', ')}]"
when 'object'
JSON.generate(value)
when 'integer', 'number', 'boolean' then value.to_s
when 'string', 'datetime' then %{"#{value}"}
else
raise ArgumentError, %{invalid or missing "type" in API property: #{prop.inspect}}
end end
end end
@ -78,8 +94,11 @@ def render_properties(json)
"{\n" + indent( "{\n" + indent(
properties.map do |name, prop| properties.map do |name, prop|
render_comment(prop['description']) + render_comment(prop['description']) +
%{"#{name}": } + render_value(prop['example'], prop['type']) %{"#{name}": } + render_value(prop)
end.join(",\n")) + end.join(",\n")) +
"\n}" "\n}"
end end
rescue
puts "error rendering properties for model:\n#{json}"
raise
end end