Update AssignmentCalendar and Rubric docs for cleaner OpenAPI doc generation

app/controllers/account_calendars_api_controller.rb

@@ -101,6 +101,28 @@
 #         }
 #       }
 #     }
+#
+# @model AccountCalendarList
+#     {
+#       "id": "AccountCalendarList",
+#       "properties": {
+#         "account_calendars": {
+#           "description": "List of account calendars",
+#           "example": ["AccountCalendar"],
+#           "type": "array",
+#           "items": {
+#             "type": "AccountCalendar"
+#           }
+#         },
+#         "total_results": {
+#           "description": "Total number of account calendars",
+#           "example": "1"
+#           "type": "integer"
+#         }
+#       }
+#     }
+#
+
 class AccountCalendarsApiController < ApplicationController
   include Api::V1::AccountCalendar
 
@@ -119,7 +141,7 @@ class AccountCalendarsApiController < ApplicationController
   #   curl https://<canvas>/api/v1/account_calendars \
   #     -H 'Authorization: Bearer <token>'
   #
-  # @returns { "account_calendars": [AccountCalendar], "total_results": "integer"}
+  # @returns AccountCalendarList
   def index
     GuardRail.activate(:secondary) do
       search_term = params[:search_term]

app/controllers/outcomes_api_controller.rb

@@ -98,6 +98,7 @@
 #         },
 #         "ratings": {
 #           "description": "possible ratings for this outcome. included only if the outcome embeds a rubric criterion. omitted in the abbreviated form.",
+#           "example": ["RubricRating"],
 #           "type": "array",
 #           "items": { "$ref" : "RubricRating" }
 #         },
@@ -124,6 +125,31 @@
 #       }
 #     }
 #
+# @model RubricRating
+#     {
+#       "id": "RubricRating",
+#       "properties": {
+#         "id": {
+#           "example": "name_2",
+#           "type": "string"
+#         },
+#         "criterion_id": {
+#           "example": "_10",
+#           "type": "string"
+#         },
+#         "description": {
+#           "type": "string"
+#         },
+#         "long_description": {
+#           "type": "string"
+#         },
+#         "points": {
+#           "example": "5",
+#           "type": "integer"
+#         }
+#       }
+#     }
+#
 # @model OutcomeAlignment
 #     {
 #       "id": "OutcomeAlignment",

app/controllers/rubrics_api_controller.rb

@@ -324,7 +324,7 @@ def used_locations
 
   # @API Creates a rubric using a CSV file
   # Returns the rubric import object that was created
-  # @returns RubricImport
+  # @returns Rubric
   def upload
     return unless authorized_action(@context, @current_user, :manage_rubrics)