From 5c4c1c79bdd7761c31bd75d33c83501ee6e6fddb Mon Sep 17 00:00:00 2001
From: Evan Battaglia <ebattaglia@instructure.com>
Date: Fri, 10 Apr 2020 16:21:27 -0600
Subject: [PATCH] Add docs for account lookup endpoint

refs PLAT-5515

Test plan:
- run rake doc:api and look and API index page
- click "Accounts (LTI)" on the side

Change-Id: Id308788ffce3b3f7babf2eebaf2f2807e549fc62
Reviewed-on: https://gerrit.instructure.com/c/canvas-lms/+/233743
Tested-by: Service Cloud Jenkins <svc.cloudjenkins@instructure.com>
Reviewed-by: Weston Dransfield <wdransfield@instructure.com>
QA-Review: Evan Battaglia <ebattaglia@instructure.com>
Product-Review: Evan Battaglia <ebattaglia@instructure.com>
---
 .../lti/account_lookup_controller.rb          | 49 +++++++++++++++++++
 config/routes.rb                              |  4 +-
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/app/controllers/lti/account_lookup_controller.rb b/app/controllers/lti/account_lookup_controller.rb
index 7a2e09eefc4..4de1f08128c 100644
--- a/app/controllers/lti/account_lookup_controller.rb
+++ b/app/controllers/lti/account_lookup_controller.rb
@@ -16,12 +16,61 @@
 # with this program. If not, see <http://www.gnu.org/licenses/>.
 
 module Lti
+  # @API Accounts (LTI)
+  #
+  # API for accessing account data using an LTI dev key. Allows a tool to get account
+  # information via LTI Advantage authorization scheme, which does not require a
+  # user session like normal developer keys do. Requires the account lookup scope on
+  # the LTI key.
+  #
+  # @model Account
+  #     {
+  #       "id": "Account",
+  #       "description": "",
+  #       "properties": {
+  #         "id": {
+  #           "description": "the ID of the Account object",
+  #           "example": 2,
+  #           "type": "integer"
+  #         },
+  #         "name": {
+  #           "description": "The display name of the account",
+  #           "example": "Canvas Account",
+  #           "type": "string"
+  #         },
+  #         "uuid": {
+  #           "description": "The UUID of the account",
+  #           "example": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5",
+  #           "type": "string"
+  #         },
+  #         "parent_account_id": {
+  #           "description": "The account's parent ID, or null if this is the root account",
+  #           "example": 1,
+  #           "type": "integer"
+  #         },
+  #         "root_account_id": {
+  #           "description": "The ID of the root account, or null if this is the root account",
+  #           "example": 1,
+  #           "type": "integer"
+  #         },
+  #         "workflow_state": {
+  #           "description": "The state of the account. Can be 'active' or 'deleted'.",
+  #           "example": "active",
+  #           "type": "string"
+  #         }
+  #       }
+  #     }
+  #
   class AccountLookupController < ApplicationController
     include Ims::Concerns::AdvantageServices
     include Api::V1::Account
 
     MIME_TYPE = 'application/vnd.canvas.accountlookup+json'.freeze
 
+    # @API Get account
+    # Retrieve information on an individual account, given by local or global ID.
+    #
+    # @returns Account
     def show
       # sending read_only=true; sending false would give more fields but passes the
       # nil session in to extensions' extend_account_json() which may not be safe
diff --git a/config/routes.rb b/config/routes.rb
index 7cf53da69bf..348ddd5a952 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -2366,7 +2366,7 @@ CanvasRails::Application.routes.draw do
       get "assignments/:assignment_id/files/:file_id/originality_report", action: :show
     end
 
-    # Line Item Service
+    # Line Item Service (LTI AGS)
     scope(controller: 'lti/ims/line_items') do
       post "courses/:course_id/line_items", action: :create, as: :lti_line_item_create
       get "courses/:course_id/line_items/:id", action: :show, as: :lti_line_item_show
@@ -2375,7 +2375,7 @@ CanvasRails::Application.routes.draw do
       delete "courses/:course_id/line_items/:id", action: :destroy, as: :lti_line_item_delete
     end
 
-    # Scores Service
+    # Scores Service (LTI AGS)
     scope(controller: 'lti/ims/scores') do
       post "courses/:course_id/line_items/:line_item_id/scores", action: :create, as: :lti_result_create
     end