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

converting @object notation to @model part 8/11 

converting for:
notification preferences controller
outcome groups controller
outcome results controller
outcome api controller
page views controller

Contributed by github.com/mcgachey

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: Ie2f42a8c3544b53e1b08ba35c7a3382afba2ab0f
Reviewed-on: https://gerrit.instructure.com/30002
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>
This commit is contained in:
Rob Orton 2014-02-11 16:22:21 -07:00
parent 972b2ec425
commit d37faa2443
5 changed files with 247 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
app/controllers/notification_preferences_controller.rb
View File

@ -20,21 +20,39 @@
#
# API for managing notification preferences
#
# @object NotificationPreference
# @model NotificationPreference
# {
# "href": "https://canvas.instructure.com/users/1/communication_channels/email/student@example.edu/notification_preferences/new_announcement",
#
# // The notification this preference belongs to
# "notification": "new_announcement",
#
# // The category of that notification
# "category": "announcement",
#
# // How often to send notifications to this communication channel
# // for the given notification. Possible values are "immediately",
# // "daily", "weekly", and "never"
# "frequency": "daily"
#
# "id": "NotificationPreference",
# "description": "",
# "properties": {
# "href": {
# "example": "https://canvas.instructure.com/users/1/communication_channels/email/student@example.edu/notification_preferences/new_announcement",
# "type": "string"
# },
# "notification": {
# "description": "The notification this preference belongs to",
# "example": "new_announcement",
# "type": "string"
# },
# "category": {
# "description": "The category of that notification",
# "example": "announcement",
# "type": "string"
# },
# "frequency": {
# "description": "How often to send notifications to this communication channel for the given notification. Possible values are 'immediately', 'daily', 'weekly', and 'never'",
# "example": "daily",
# "type": "string",
# "allowableValues": {
# "values": [
# "immediately",
# "daily",
# "weekly",
# "never"
# ]
# }
# }
# }
# }
#
class NotificationPreferencesController < ApplicationController

170
app/controllers/outcome_groups_api_controller.rb
View File

@ -31,91 +31,99 @@
# While an outcome can be linked into a context (such as a course) multiple
# times, it may only be linked into a particular group once.
#
# @object OutcomeGroup
#
# @model OutcomeGroup
# {
# // the ID of the outcome group
# "id": 1,
#
# // the URL for fetching/updating the outcome group. should be treated
# // as opaque
# "url": "/api/v1/accounts/1/outcome_groups/1",
#
# // an abbreviated OutcomeGroup object representing the parent group of
# // this outcome group, if any. omitted in the abbreviated form.
# "parent_outcome_group": {
# "id": 1337,
# "url": "http://...",
# "title": "title",
# "subgroups_url": "http://...",
# "outcomes_url": "http://...",
# "can_edit": true
# },
#
# // the context owning the outcome group. may be null for global outcome
# // groups. omitted in the abbreviated form.
# "context_id": 1,
# "context_type": "Account",
#
# // title of the outcome group
# "title": "Outcome group title",
#
# // description of the outcome group. omitted in the abbreviated form.
# "description": "Outcome group description",
#
# // A custom GUID for the learning standard.
# "vendor_guid": "customid9000",
#
# // the URL for listing/creating subgroups under the outcome group.
# // should be treated as opaque
# "subgroups_url": "/api/v1/accounts/1/outcome_groups/1/subgroups",
#
# // the URL for listing/creating outcome links under the outcome group.
# // should be treated as opaque
# "outcomes_url": "/api/v1/accounts/1/outcome_groups/1/outcomes",
#
# // the URL for importing another group into this outcome group. should
# // be treated as opaque. omitted in the abbreviated form.
# "import_url": "/api/v1/accounts/1/outcome_groups/1/import",
#
# // whether the current user can update the outcome group
# "can_edit": true
# "id": "OutcomeGroup",
# "description": "",
# "properties": {
# "id": {
# "description": "the ID of the outcome group",
# "example": 1,
# "type": "integer"
# },
# "url": {
# "description": "the URL for fetching/updating the outcome group. should be treated as opaque",
# "example": "/api/v1/accounts/1/outcome_groups/1",
# "type": "string"
# },
# "parent_outcome_group": {
# "description": "an abbreviated OutcomeGroup object representing the parent group of this outcome group, if any. omitted in the abbreviated form.",
# "$ref": "OutcomeGroup"
# },
# "context_id": {
# "description": "the context owning the outcome group. may be null for global outcome groups. omitted in the abbreviated form.",
# "example": 1,
# "type": "integer"
# },
# "context_type": {
# "example": "Account",
# "type": "string"
# },
# "title": {
# "description": "title of the outcome group",
# "example": "Outcome group title",
# "type": "string"
# },
# "description": {
# "description": "description of the outcome group. omitted in the abbreviated form.",
# "example": "Outcome group description",
# "type": "string"
# },
# "vendor_guid": {
# "description": "A custom GUID for the learning standard.",
# "example": "customid9000",
# "type": "string"
# },
# "subgroups_url": {
# "description": "the URL for listing/creating subgroups under the outcome group. should be treated as opaque",
# "example": "/api/v1/accounts/1/outcome_groups/1/subgroups",
# "type": "string"
# },
# "outcomes_url": {
# "description": "the URL for listing/creating outcome links under the outcome group. should be treated as opaque",
# "example": "/api/v1/accounts/1/outcome_groups/1/outcomes",
# "type": "string"
# },
# "import_url": {
# "description": "the URL for importing another group into this outcome group. should be treated as opaque. omitted in the abbreviated form.",
# "example": "/api/v1/accounts/1/outcome_groups/1/import",
# "type": "string"
# },
# "can_edit": {
# "description": "whether the current user can update the outcome group",
# "example": true,
# "type": "boolean"
# }
# }
# }
#
# @object OutcomeLink
# @model OutcomeLink
# {
# // the URL for fetching/updating the outcome link. should be treated as
# // opaque
# "url": "/api/v1/account/1/outcome_groups/1/outcomes/1",
#
# // the context owning the outcome link. will match the context owning
# // the outcome group containing the outcome link; included for
# // convenience. may be null for links in global outcome groups.
# "context_id": 1,
# "context_type": "Account",
#
# // an abbreviated OutcomeGroup object representing the group containing
# // the outcome link.
# "outcome_group": {
# "id": 1,
# "url": "http://...",
# "title": "title",
# "vendor_guid": "af827ef88a",
# "subgroups_url": "http://...",
# "outcomes_url": "http://...",
# "can_edit": true
# },
#
# // an abbreviated Outcome object representing the outcome linked into
# // the containing outcome group.
# "outcome": {
# "id": 1,
# "url": "http://...",
# "vendor_guid": "af827ef88a",
# "context_id": 3392,
# "context_type": "Course",
# "title": "title",
# "can_edit": true
# "id": "OutcomeLink",
# "description": "",
# "properties": {
# "url": {
# "description": "the URL for fetching/updating the outcome link. should be treated as opaque",
# "example": "/api/v1/account/1/outcome_groups/1/outcomes/1",
# "type": "string"
# },
# "context_id": {
# "description": "the context owning the outcome link. will match the context owning the outcome group containing the outcome link; included for convenience. may be null for links in global outcome groups.",
# "example": 1,
# "type": "integer"
# },
# "context_type": {
# "example": "Account",
# "type": "string"
# },
# "outcome_group": {
# "description": "an abbreviated OutcomeGroup object representing the group containing the outcome link.",
# "$ref": "OutcomeGroup"
# },
# "outcome": {
# "description": "an abbreviated Outcome object representing the outcome linked into the containing outcome group.",
# "$ref": "OutcomeGroup"
# }
# }
# }
#

95
app/controllers/outcome_results_controller.rb
View File

@ -21,43 +21,80 @@
#
# API for accessing learning outcome results
#
# @object OutcomeRollupScore
# @model OutcomeRollupScoreLinks
# {
# // The rollup score for the outcome, based on the student assessment
# // scores related to the outcome. This could be null if the student has
# // no related scores.
# "score": 3,
#
# "links": {
# // The id of the related outcome
# "outcome": "42"
# "id": "OutcomeRollupScoreLinks",
# "description": "",
# "properties": {
# "outcome": {
# "description": "The id of the related outcome",
# "example": 42,
# "type": "integer"
# }
# }
# }
#
# @object OutcomeRollup
# @model OutcomeRollupScore
# {
# // an array of OutcomeRollupScore objects
# "scores": ["OutcomeRollupScore"],
#
# // The name of the resource for this rollup. For example, the user name.
# "name": "John Doe",
#
# "links": {
# // If an aggregate result was requested, the course field will be present
# // Otherwise, the user and section field will be present
#
# // (Optional) The id of the course that this rollup applies to
# "course": "42",
#
# // (Optional) The id of the user that this rollup applies to
# "user": "42",
#
# // (Optional) The id of the section the user is in
# "section": "57"
# "id": "OutcomeRollupScore",
# "description": "",
# "properties": {
# "score": {
# "description": "The rollup score for the outcome, based on the student assessment scores related to the outcome. This could be null if the student has no related scores.",
# "example": 3,
# "type": "integer"
# },
# "links": {
# "example": "{\"outcome\"=>\"42\"}",
# "$ref": "OutcomeRollupScoreLinks"
# }
# }
# }
#
# @model OutcomeRollupLinks
# {
# "id": "OutcomeRollupLinks",
# "description": "",
# "properties": {
# "course": {
# "description": "If an aggregate result was requested, the course field will be present Otherwise, the user and section field will be present (Optional) The id of the course that this rollup applies to",
# "example": 42,
# "type": "integer"
# },
# "user": {
# "description": "(Optional) The id of the user that this rollup applies to",
# "example": 42,
# "type": "integer"
# },
# "section": {
# "description": "(Optional) The id of the section the user is in",
# "example": 57,
# "type": "integer"
# }
# }
# }
#
# @model OutcomeRollup
# {
# "id": "OutcomeRollup",
# "description": "",
# "properties": {
# "scores": {
# "description": "an array of OutcomeRollupScore objects",
# "$ref": "OutcomeRollupScore"
# },
# "name": {
# "description": "The name of the resource for this rollup. For example, the user name.",
# "example": "John Doe",
# "type": "string"
# },
# "links": {
# "example": "{\"course\"=>42, \"user\"=>42, \"section\"=>57}",
# "$ref": "OutcomeRollupLinks"
# }
# }
# }
#
class OutcomeResultsController < ApplicationController
include Api::V1::OutcomeResults
include Outcomes::ResultAnalytics

100
app/controllers/outcomes_api_controller.rb
View File

@ -20,48 +20,66 @@
#
# API for accessing learning outcome information.
#
# @object Outcome
#
# @model Outcome
# {
# // the ID of the outcome
# "id": 1,
#
# // the URL for fetching/updating the outcome. should be treated as
# // opaque
# "url": "/api/v1/outcomes/1",
#
# // the context owning the outcome. may be null for global outcomes
# "context_id": 1,
# "context_type": "Account",
#
# // title of the outcome
# "title": "Outcome title",
#
# // description of the outcome. omitted in the abbreviated form.
# "description": "Outcome description",
#
# // A custom GUID for the learning standard.
# "vendor_guid": "customid9000",
#
# // maximum points possible. included only if the outcome embeds a
# // rubric criterion. omitted in the abbreviated form.
# "points_possible": 5,
#
# // points necessary to demonstrate mastery outcomes. included only if
# // the outcome embeds a rubric criterion. omitted in the abbreviated
# // form.
# "mastery_points": 3,
#
# // possible ratings for this outcome. included only if the outcome
# // embeds a rubric criterion. omitted in the abbreviated form.
# "ratings": [
# { "description": "Exceeds Expectations", "points": 5 },
# { "description": "Meets Expectations", "points": 3 },
# { "description": "Does Not Meet Expectations", "points": 0 }
# ],
#
# // whether the current user can update the outcome
# "can_edit": true
# "id": "Outcome",
# "description": "",
# "properties": {
# "id": {
# "description": "the ID of the outcome",
# "example": 1,
# "type": "integer"
# },
# "url": {
# "description": "the URL for fetching/updating the outcome. should be treated as opaque",
# "example": "/api/v1/outcomes/1",
# "type": "string"
# },
# "context_id": {
# "description": "the context owning the outcome. may be null for global outcomes",
# "example": 1,
# "type": "integer"
# },
# "context_type": {
# "example": "Account",
# "type": "string"
# },
# "title": {
# "description": "title of the outcome",
# "example": "Outcome title",
# "type": "string"
# },
# "description": {
# "description": "description of the outcome. omitted in the abbreviated form.",
# "example": "Outcome description",
# "type": "string"
# },
# "vendor_guid": {
# "description": "A custom GUID for the learning standard.",
# "example": "customid9000",
# "type": "string"
# },
# "points_possible": {
# "description": "maximum points possible. included only if the outcome embeds a rubric criterion. omitted in the abbreviated form.",
# "example": 5,
# "type": "integer"
# },
# "mastery_points": {
# "description": "points necessary to demonstrate mastery outcomes. included only if the outcome embeds a rubric criterion. omitted in the abbreviated form.",
# "example": 3,
# "type": "integer"
# },
# "ratings": {
# "description": "possible ratings for this outcome. included only if the outcome embeds a rubric criterion. omitted in the abbreviated form.",
# "type": "array",
# "items": { "$ref" : "RubricRating" }
# },
# "can_edit": {
# "description": "whether the current user can update the outcome",
# "example": true,
# "type": "boolean"
# }
# }
# }
#
class OutcomesApiController < ApplicationController

2
app/controllers/page_views_controller.rb
View File

@ -110,7 +110,7 @@
# }
# }
#
# @object PageViewLinks
# @model PageViewLinks
# {
# "id": "PageViewLinks",
# "description": "The links of a page view access in Canvas",