From 67225b3a4bdc09986da7cdf1a125d610862fece3 Mon Sep 17 00:00:00 2001
From: David Jay <davidgljay@gmail.com>
Date: Tue, 20 Dec 2016 13:39:04 -0800
Subject: [PATCH 1/8] Updating documentation for actions.

---
 docs/swagger.yaml | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index f6aba4d25..808e11dfd 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -458,14 +458,22 @@ definitions:
     properties:
       item_id:
         type: string
+        description: The ID of the item which these actions target
       item_type:
-        type: string # comment, user...
+        type: string
+        description: The type of item which these actions target (comment, user, etc.)
       type:
-        type: string # flagged, likes, upvotes...
+        type: string
+        description: The type of action (like, flag, etc.)
       count:
         type: integer
+        description: The number of this type of actions performed on this item.
+      metadata:
+        type: array
+        description: An array of metadata from the actions performed on this item. This metadata can be defined differently for each action type.
       current_user:
-        type: boolean
+        type: Object
+        description: Will include the action performed by the currently logged in user if that user has taken an action on this item. Otherwise will return null.
   Action:
     type: object
     properties:

From c4510c1abf2c353a55f2a7dc91ffba6c42c9d247 Mon Sep 17 00:00:00 2001
From: David Jay <davidgljay@gmail.com>
Date: Tue, 20 Dec 2016 13:43:38 -0800
Subject: [PATCH 2/8] Updating action documentation.

---
 client/coral-framework/actions/items.js | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/client/coral-framework/actions/items.js b/client/coral-framework/actions/items.js
index 160dcb24c..243429863 100644
--- a/client/coral-framework/actions/items.js
+++ b/client/coral-framework/actions/items.js
@@ -208,7 +208,9 @@ export function postItem (item, type, id) {
 *
 * @params
 *   id - the id of the item on which the action is taking place
-*   action - the name of the action
+*   action - the action object.
+*       Must include an 'action_type' string.
+*       May optionally include a `metadata` object with arbitrary action data.
 *   user - the user performing the action
 *   host - the coral host
 *

From d998549fd0653a94984dd6a1f13656586537b059 Mon Sep 17 00:00:00 2001
From: David Jay <davidgljay@gmail.com>
Date: Tue, 20 Dec 2016 16:16:10 -0800
Subject: [PATCH 3/8] Updating swagger docs.

---
 docs/swagger.yaml | 147 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 136 insertions(+), 11 deletions(-)

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index 808e11dfd..6c1256b39 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -423,10 +423,6 @@ definitions:
       message:
         type: string
         description: The error that occured.
-  Item:
-    type: object
-  ModerationAction:
-    type: string
   Comment:
     type: object
     properties:
@@ -453,8 +449,29 @@ definitions:
       asset_id:
         type: string
         description: Display name of comment
+      status_history:
+        type: array
+        description: A history of status changes for this comment.
+        items:
+          type: object
+          properties:
+            type:
+              type: string
+              enum:
+                - accepted
+                - rejected
+                - premod
+            assigned_by:
+              type: string
+              description: ID of the user who assigned this status.
+            created_at:
+              type: string
+              format: date-time
+              description: Date when status was assigned.
+
   Actions:
     type: object
+    description: A summary of actions taken on a particular item which is with the comment stream.
     properties:
       item_id:
         type: string
@@ -470,22 +487,28 @@ definitions:
         description: The number of this type of actions performed on this item.
       metadata:
         type: array
-        description: An array of metadata from the actions performed on this item. This metadata can be defined differently for each action type.
+        items:
+          type: object
+          description: Metadata from the actions performed on this item. This metadata can be defined differently for each action type.
       current_user:
-        type: Object
+        type: object
         description: Will include the action performed by the currently logged in user if that user has taken an action on this item. Otherwise will return null.
   Action:
     type: object
+    description: A single action taken by a user.
     properties:
+      id:
+        type: string
+        description: The uuid.v4 id of the action.
       type:
         type: string
+        description: The type of action being taken (like, flag, etc.)
       user_id:
         type: string
-      moderation:
-        type: string
-        enum:
-            - pre
-            - post
+        description: The ID of the user taking this action.
+      metadata:
+        type: object
+        description: An object which contains arbitrary metadata about the action. Should be consistent for each action_type.
       created_at:
         type: string
         format: date-time
@@ -526,10 +549,112 @@ definitions:
         type: string
         format: datetime
         description: When this asset was published.
+      created_at:
+        type: string
+        format: date-time
+        description: Creation Date-Time
+      updated_at:
+        type: string
+        format: date-time
+        description: Updated Date-Time
   User:
     type: object
+    properties:
+      id:
+        type: string
+        description: The uuid.v4 id of the user.
+      displayName:
+        type: string
+        description: The name appearing next to the user's comments.
+      disabled:
+        type: boolean
+        description: Indicates whether the user's account has been disabled (ie if the user is banned).
+      password:
+        type: string
+        description: This provides a source of identity proof for users who login using the local provider. A local provider will be assumed for users who do not have any social profiles.
+      profiles:
+        type: array
+        description: The array of identities for a given user. Any one user can have multiple profiles associated with them (eg facebook, google, etc.)
+        items:
+          type: object
+          properties:
+              id:
+                type: string
+                description: A unique identifier for the profile.
+              provider:
+                type: string
+                description: The ame of the identity provider being used (e.g. 'facebook', 'twitter', etc.)
+      roles:
+        type: array
+        items:
+          type: string
+        description: Roles occupied by the user (e.g. 'admin', 'moderator', etc.)
+      status:
+        type: string
+        description: The current status of the user in the system.
+        enum:
+          - active
+          - banned
+      settings:
+        type: object
+        description: User-specific settings
+        properties:
+          bio:
+            type: string
+            description: A bio visible to other users.
+      created_at:
+        type: string
+        format: date-time
+        description: Creation Date-Time
+      updated_at:
+        type: string
+        format: date-time
+        description: Updated Date-Time
   Settings:
     type: object
+    properties:
+        id:
+          type: string
+          description: The id of the settings object. Defaults to 1 for global settings.
+        moderation:
+          type: string
+          enum:
+            - pre
+            - post
+          description: Indicates whether moderation occurs before or after a comment is made publicly visible.
+        infoBoxEnable:
+          type: boolean
+          description: Indicates whether an informational box will be shown above the comment input box.
+        infoBoxContent:
+          type: string
+          description: The text to appear in the informational box.
+        closedTimeout:
+          type: number
+          format: int32
+          description: The time after which streams will be automatically closed in seconds. Null will keep streams open forever.
+        closedMessage:
+          type: string
+          description: The message displayed when a stream is closed.
+        wordlist:
+          type: array
+          description: A list of banned word which will cause a comment to be automatically rejected.
+          items:
+            type: string
+        charCount:
+          type: number
+          format: int32
+          description: The maximum number of characters allowed in a comment.
+        charCountEnable:
+          type: boolean
+          description: Indicates whether a maximum character count should be enabled for comments.
+        created_at:
+          type: string
+          format: date-time
+          description: Creation Date-Time
+        updated_at:
+          type: string
+          format: date-time
+          description: Updated Date-Time
   Job:
     type: object
     properties:

From 8f877b87cb1531a79be5ec66985d36bf55864c0d Mon Sep 17 00:00:00 2001
From: David Jay <davidgljay@gmail.com>
Date: Wed, 21 Dec 2016 11:32:30 -0800
Subject: [PATCH 4/8] Adding swagger endpoints.

---
 docs/swagger.yaml | 137 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 122 insertions(+), 15 deletions(-)

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index 6c1256b39..a5d71119b 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -18,12 +18,10 @@ paths:
       tags:
         - Comments
       parameters:
-        - name: status
+        - name: asset_id
           in: query
-          description: Performs a search based on the comment's status.
+          description: Returns comments for a particular asset, if null returns all commets.
           type: string
-          enum:
-            - flag
         - name: action_type
           in: query
           description: Performs a search based on the actions that have been added to it.
@@ -49,9 +47,18 @@ paths:
       parameters:
         - name: body
           in: body
-          description: The comment to create.
+          type: string
+          description: The text of comment to create.
           schema:
             $ref: '#/definitions/Comment'
+        - name: asset_id
+          in: body
+          type: string
+          description: The parent asset of this comment.
+        - name: parent_id
+          in: body
+          type: string
+          description: The parent comment of this comment (null if the comment is not a reply.)
       responses:
         201:
           description: The comment that was created.
@@ -132,9 +139,9 @@ paths:
         - Comments
         - Actions
       parameters:
-        - name: comment_id
+        - name: item_id
           in: path
-          description: The id of the comment to retrieve.
+          description: The id of the item which is the target of the action.
           type: string
           required: true
         - name: body
@@ -146,7 +153,10 @@ paths:
             properties:
               action_type:
                 type: string
-                description: The action to add
+                description: The type of action to add
+              metadata:
+                type: object
+                description: An arbitrary object describing the action, should be consistent per action type.
       responses:
         201:
           description: The action created.
@@ -240,6 +250,19 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
+  /auth/facebook/callback:
+    get:
+      tags:
+        - Auth
+      responses:
+        200:
+          description: Logs in the user after FB Auth.
+          schema:
+            $ref: '#/definitions/User'
+        500:
+          description: An error occured.
+          schema:
+            $ref: '#/definitions/Error'
   /queue/comments/pending:
     get:
       tags:
@@ -249,9 +272,23 @@ paths:
         200:
           description: The comments that are not moderated.
           schema:
-            type: array
-            items:
-              - $ref: '#/definitions/Comment'
+            type: object
+            properties:
+              comments:
+                type: array
+                description: The comments that have yet to be moderated.
+                items:
+                  - $ref: '#/definitions/Comment'
+              users:
+                type: array
+                description: The users authoring these comments.
+                items:
+                  - $ref: '#/definitions/User'
+              actions:
+                type: array
+                description: The actions which have taken place on these comments.
+                items:
+                  - $ref: '#/definitions/Actions'
         500:
           description: An error occured.
           schema:
@@ -280,6 +317,17 @@ paths:
           in: query
           type: string
           description: Field to sort by.
+        - name: filter
+          in: query
+          type: string
+          enum:
+            - open
+            - closed
+          description: Comment status to filter by.
+        - name: search
+          in: query
+          type: string
+          description: String to search by.
       responses:
         200:
           description: Assets listed.
@@ -358,6 +406,31 @@ paths:
           schema:
             $ref: '#/definitions/Error'
 
+  /assets/{asset_id}/settings:
+    put:
+      parameters:
+        asset_id:
+          in: path
+          required: true
+          type: string
+          format: uuid
+          description: The id of the asset to be updated
+        body:
+          in: body
+          type: object
+          parameters:
+            closedAt:
+              type: number
+              description: The Unix timestamp when the stream will be or was previously closed.
+            closedMessage:
+              type: string
+              description: The message to display to users when the stream is closed.
+        responses:
+          204:
+            description: Status update successful.
+          500:
+            description: An error has occurred.
+
   /stream:
     get:
       tags:
@@ -368,7 +441,7 @@ paths:
       parameters:
         - name: asset_url
           in: query
-          description: The asset url to get the comment stream from.
+          description: The url of the asset for which to get the comment stream.
           type: string
           format: url
       responses:
@@ -377,20 +450,24 @@ paths:
           schema:
             type: object
             properties:
-              assets:
-                type: array
+              asset:
+                type: object
+                description: The asset for the url passed to this endpoint.
                 items:
                   - $ref: '#/definitions/Asset'
               comments:
                 type: array
+                description: All comments for this asset.
                 items:
                   - $ref: '#/definitions/Comment'
               users:
                 type: array
+                description: All authors of comments on this asset.
                 items:
                   - $ref: '#/definitions/User'
               actions:
                 type: array
+                description: All actions on comments on this asset and their authors.
                 items:
                   - $ref: '#/definitions/Actions'
         500:
@@ -401,7 +478,7 @@ paths:
     get:
       responses:
         200:
-          description: The settings.
+          description: All global settings.
           schema:
             $ref: '#/definitions/Settings'
         500:
@@ -410,12 +487,42 @@ paths:
             $ref: '#/definitions/Error'
     put:
       responses:
+        parameteters:
+          body:
+            type: object
+            description: Settings to be updated
         204:
           description: The settings were updated.
         500:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
+    /users:
+      get:
+        value:
+          in: query
+          type: string
+          description: A term to search users' displayNames and email addresses.
+        sort:
+          in: query
+          type: string
+          enum:
+            asc
+            desc
+          description: Determines whether users sorted in are ascending or descending order.
+        field:
+          in: query
+          type: string
+          description: The field used to sort.
+        page:
+          in: query
+          type: number
+          description: The page of search results to return.
+        limit:
+          in: query
+          type: number
+          description: The number of search restults per page.
+
 definitions:
   Error:
     type: object

From 00cf81563e58917072b7f6249542dcef395643db Mon Sep 17 00:00:00 2001
From: David Jay <davidgljay@gmail.com>
Date: Wed, 21 Dec 2016 12:01:37 -0800
Subject: [PATCH 5/8] Adding user endpoints to swagger.

---
 docs/swagger.yaml | 79 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 1 deletion(-)

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index a5d71119b..f45c86fe2 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -522,7 +522,84 @@ paths:
           in: query
           type: number
           description: The number of search restults per page.
-
+      responses:
+        200:
+          parameters:
+            result:
+              type: array
+              description: Users matching search criteria.
+              items:
+                $ref: '#/definitions/User'
+            limit:
+              type: number
+              description: Results per page.
+            count:
+              type: number
+              description: Total number of results.
+            page:
+              type: number
+              description: The current page.
+            totalPages:
+              type: number
+              description: The total number of pages.
+        500:
+          description: An error occured.
+          schema:
+            $ref: '#/definitions/Error'
+  /users/:user_id/role:
+    post:
+      user_id:
+        in: path
+        type: string
+        format: uuid
+        description: ID of the user to be updated.
+      body:
+        in: body
+        type: object
+        parameters:
+          role:
+            type: string
+            description: Role to be added to the user.
+            enum:
+              admin
+              moderator
+      responses:
+        204:
+          description: Role update successful.
+        500:
+          description: An error occured.
+          schema:
+            $ref: '#/definitions/Error'
+  /users/:user_id/status:
+    post:
+      user_id:
+        in: path
+        type: string
+        format: uuid
+        required: true
+        description: ID of the user to be updated.
+      body:
+        in: body
+        type: object
+        parameters:
+          status:
+            type: string
+            required: true
+            description: Status for the user to be set to.
+            enum:
+              active
+              banned
+          comment_id:
+            type: string
+            format: uuid
+            description: The id of the comment which triggered this status change.
+      responses:
+        200:
+          description: Status update successful.
+        500:
+          description: An error occured.
+          schema:
+            $ref: '#/definitions/Error'
 definitions:
   Error:
     type: object

From 81ff5420fe561146684889e12718109ca85ca13f Mon Sep 17 00:00:00 2001
From: David Jay <davidgljay@gmail.com>
Date: Wed, 21 Dec 2016 15:26:47 -0800
Subject: [PATCH 6/8] Completing user endpoitn updates.

---
 docs/swagger.yaml | 179 +++++++++++++++++++++++++++++++++++-----------
 1 file changed, 136 insertions(+), 43 deletions(-)

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index f45c86fe2..a3707c444 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -497,51 +497,103 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
-    /users:
-      get:
-        value:
-          in: query
-          type: string
-          description: A term to search users' displayNames and email addresses.
-        sort:
-          in: query
-          type: string
-          enum:
-            asc
-            desc
-          description: Determines whether users sorted in are ascending or descending order.
-        field:
-          in: query
-          type: string
-          description: The field used to sort.
-        page:
-          in: query
-          type: number
-          description: The page of search results to return.
-        limit:
-          in: query
-          type: number
-          description: The number of search restults per page.
+  /users:
+    get:
+      value:
+        in: query
+        type: string
+        description: A term to search users' displayNames and email addresses.
+      sort:
+        in: query
+        type: string
+        enum:
+          asc
+          desc
+        description: Determines whether users sorted in are ascending or descending order.
+      field:
+        in: query
+        type: string
+        description: The field used to sort.
+      page:
+        in: query
+        type: number
+        description: The page of search results to return.
+      limit:
+        in: query
+        type: number
+        description: The number of search restults per page.
+    responses:
+      200:
+        parameters:
+          result:
+            type: array
+            description: Users matching search criteria.
+            items:
+              $ref: '#/definitions/User'
+          limit:
+            type: number
+            description: Results per page.
+          count:
+            type: number
+            description: Total number of results.
+          page:
+            type: number
+            description: The current page.
+          totalPages:
+            type: number
+            description: The total number of pages.
+      500:
+        description: An error occured.
+        schema:
+          $ref: '#/definitions/Error'
+    post:
+      body:
+        in: body
+        type: object
+        parameters:
+          email:
+            type: string
+            format: email
+          password:
+            type: string
+          displayName:
+            type: string
       responses:
-        200:
+        201:
+          description: The user that has been created.
+          schema:
+            $ref: '#/definitions/User'
+    /users/update-password:
+      post:
+        body:
+          in: body
+          type: object
           parameters:
-            result:
-              type: array
-              description: Users matching search criteria.
-              items:
-                $ref: '#/definitions/User'
-            limit:
-              type: number
-              description: Results per page.
-            count:
-              type: number
-              description: Total number of results.
-            page:
-              type: number
-              description: The current page.
-            totalPages:
-              type: number
-              description: The total number of pages.
+            token:
+              type: string
+              description: The token that was in the url of the email link.
+            password:
+              type: string
+              description: The new password.
+      response:
+        204:
+          description: Password update successful.
+        500:
+          description: An error occured.
+          schema:
+            $ref: '#/definitions/Error'
+    /request-password-reset:
+      post:
+        body:
+          in: body
+          type: object
+          parameters:
+            email:
+              type: string
+              description: The email address of the user whos password is being reset.
+      response:
+        204:
+          description: Returned regardless of whether the user was found in the DB.
         500:
           description: An error occured.
           schema:
@@ -600,6 +652,47 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
+  /users/:user_id/bio:
+    put:
+      user_id:
+        in: path
+        type: string
+        format: uuid
+        description: The id of the user being updated.
+      bio:
+        in: body
+        type: string
+        description: The bio that should be set for this user.
+      responses:
+        200:
+          description: Status update successful.
+          schema:
+            $ref: '#/definitions/User'
+        500:
+          description: An error occured.
+          schema:
+            $ref: '#/definitions/Error'
+  /:user_id/actions:
+    post:
+      action_type:
+        in: body
+        type: string
+        enum:
+          flag
+        description: The type of action being taken on this user.
+      metadata:
+        in: body
+        type: object
+        description: Arbitrary data to be included with the action.
+      responses:
+        200:
+          description: The newly created action.
+          schema:
+            $ref: '#/definitions/Action'
+        500:
+          description: An error occured.
+          schema:
+            $ref: '#/definitions/Error'
 definitions:
   Error:
     type: object

From 510b3754aadad9cb776db85c853a2f0ab5b92b51 Mon Sep 17 00:00:00 2001
From: David Jay <davidgljay@gmail.com>
Date: Wed, 21 Dec 2016 17:43:06 -0800
Subject: [PATCH 7/8] Properly formatting swagger docs.

---
 docs/swagger.yaml | 130 +++++++++++++++++++++++-----------------------
 1 file changed, 65 insertions(+), 65 deletions(-)

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index a3707c444..b3030fc3c 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -18,10 +18,6 @@ paths:
       tags:
         - Comments
       parameters:
-        - name: asset_id
-          in: query
-          description: Returns comments for a particular asset, if null returns all commets.
-          type: string
         - name: action_type
           in: query
           description: Performs a search based on the actions that have been added to it.
@@ -47,18 +43,20 @@ paths:
       parameters:
         - name: body
           in: body
-          type: string
-          description: The text of comment to create.
           schema:
-            $ref: '#/definitions/Comment'
-        - name: asset_id
-          in: body
-          type: string
-          description: The parent asset of this comment.
-        - name: parent_id
-          in: body
-          type: string
-          description: The parent comment of this comment (null if the comment is not a reply.)
+            body:
+              in: body
+              type: string
+              required: true
+              description: The text of the comment to create.
+            asset_id:
+              in: body
+              type: string
+              description: The parent asset of this comment.
+            parent_id:
+              in: body
+              type: string
+              description: The parent comment of this comment (null if the comment is not a reply.)
       responses:
         201:
           description: The comment that was created.
@@ -68,7 +66,8 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
-  /comments/{comment_id}:
+
+  /comments/:comment_id:
     get:
       tags:
         - Comments
@@ -105,6 +104,7 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
+
   /comments/{comment_id}/status:
     put:
       tags:
@@ -406,7 +406,7 @@ paths:
           schema:
             $ref: '#/definitions/Error'
 
-  /assets/{asset_id}/settings:
+  /assets/:asset_id/settings:
     put:
       parameters:
         asset_id:
@@ -415,22 +415,19 @@ paths:
           type: string
           format: uuid
           description: The id of the asset to be updated
-        body:
+        closedAt:
           in: body
-          type: object
-          parameters:
-            closedAt:
-              type: number
-              description: The Unix timestamp when the stream will be or was previously closed.
-            closedMessage:
-              type: string
-              description: The message to display to users when the stream is closed.
+          type: number
+          description: The Unix timestamp when the stream will be or was previously closed.
+        closedMessage:
+          type: string
+          in: body
+          description: The message to display to users when the stream is closed.
         responses:
           204:
             description: Status update successful.
           500:
             description: An error has occurred.
-
   /stream:
     get:
       tags:
@@ -598,23 +595,24 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
-  /users/:user_id/role:
+  /users/{user_id}/role:
     post:
-      user_id:
-        in: path
-        type: string
-        format: uuid
-        description: ID of the user to be updated.
-      body:
-        in: body
-        type: object
-        parameters:
-          role:
-            type: string
-            description: Role to be added to the user.
-            enum:
-              admin
-              moderator
+      parameters:
+        user_id:
+          in: path
+          type: string
+          format: uuid
+          description: ID of the user to be updated.
+        body:
+          in: body
+          type: object
+          parameters:
+            role:
+              type: string
+              description: Role to be added to the user.
+              enum:
+                admin
+                moderator
       responses:
         204:
           description: Role update successful.
@@ -622,7 +620,7 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
-  /users/:user_id/status:
+  /users/{user_id}/status:
     post:
       user_id:
         in: path
@@ -652,17 +650,18 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
-  /users/:user_id/bio:
+  /users/{user_id}/bio:
     put:
-      user_id:
-        in: path
-        type: string
-        format: uuid
-        description: The id of the user being updated.
-      bio:
-        in: body
-        type: string
-        description: The bio that should be set for this user.
+      parameters:
+        user_id:
+          in: path
+          type: string
+          format: uuid
+          description: The id of the user being updated.
+        bio:
+          in: body
+          type: string
+          description: The bio that should be set for this user.
       responses:
         200:
           description: Status update successful.
@@ -672,18 +671,19 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
-  /:user_id/actions:
+  /{user_id}/actions:
     post:
-      action_type:
-        in: body
-        type: string
-        enum:
-          flag
-        description: The type of action being taken on this user.
-      metadata:
-        in: body
-        type: object
-        description: Arbitrary data to be included with the action.
+      parameters:
+        - name: action_type
+          in: body
+          description: The type of action being taken on this user.
+          type: string
+          enum:
+            - flag
+        - name: metadata
+          in: body
+          type: object
+          description: Arbitrary data to be included with the action.
       responses:
         200:
           description: The newly created action.

From ec455c99af360616fc5ea3a288a63f40bc630545 Mon Sep 17 00:00:00 2001
From: David Jay <davidgljay@gmail.com>
Date: Wed, 21 Dec 2016 17:53:55 -0800
Subject: [PATCH 8/8] Making small corrections to swagger.

---
 docs/swagger.yaml | 385 ++++++++++++++++++++++++++--------------------
 1 file changed, 218 insertions(+), 167 deletions(-)

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index b3030fc3c..8fe8627b0 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -32,7 +32,7 @@ paths:
           schema:
             type: array
             items:
-              - $ref: '#/definitions/Comment'
+              $ref: '#/definitions/Comment'
         500:
           description: An error occured.
           schema:
@@ -43,20 +43,19 @@ paths:
       parameters:
         - name: body
           in: body
+          required: true
           schema:
-            body:
-              in: body
-              type: string
-              required: true
-              description: The text of the comment to create.
-            asset_id:
-              in: body
-              type: string
-              description: The parent asset of this comment.
-            parent_id:
-              in: body
-              type: string
-              description: The parent comment of this comment (null if the comment is not a reply.)
+            type: object
+            properties:
+              body:
+                type: string
+                description: The text of the comment to create.
+              asset_id:
+                type: string
+                description: The parent asset of this comment.
+              parent_id:
+                type: string
+                description: The parent comment of this comment (null if the comment is not a reply.)
       responses:
         201:
           description: The comment that was created.
@@ -67,7 +66,7 @@ paths:
           schema:
             $ref: '#/definitions/Error'
 
-  /comments/:comment_id:
+  /comments/{comment_id}:
     get:
       tags:
         - Comments
@@ -115,6 +114,7 @@ paths:
           in: path
           description: The id of the comment to retrieve.
           type: string
+          format: uuid
           required: true
         - name: body
           in: body
@@ -126,6 +126,11 @@ paths:
               status:
                 type: string
                 description: The status to update to.
+                enum:
+                  - new
+                  - flagged
+                  - accepted
+                  - rejected
       responses:
         204:
           description: The comment status was updated.
@@ -133,7 +138,7 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
-  /comments/{comment_id}/actions:
+  /comments/{item_id}/actions:
     post:
       tags:
         - Comments
@@ -154,6 +159,9 @@ paths:
               action_type:
                 type: string
                 description: The type of action to add
+                enum:
+                  - like
+                  - flag
               metadata:
                 type: object
                 description: An arbitrary object describing the action, should be consistent per action type.
@@ -278,17 +286,17 @@ paths:
                 type: array
                 description: The comments that have yet to be moderated.
                 items:
-                  - $ref: '#/definitions/Comment'
+                  $ref: '#/definitions/Comment'
               users:
                 type: array
                 description: The users authoring these comments.
                 items:
-                  - $ref: '#/definitions/User'
+                  $ref: '#/definitions/User'
               actions:
                 type: array
                 description: The actions which have taken place on these comments.
                 items:
-                  - $ref: '#/definitions/Actions'
+                  $ref: '#/definitions/Actions'
         500:
           description: An error occured.
           schema:
@@ -406,28 +414,34 @@ paths:
           schema:
             $ref: '#/definitions/Error'
 
-  /assets/:asset_id/settings:
+  /assets/{asset_id}/status:
     put:
       parameters:
-        asset_id:
-          in: path
+        - name: asset_id
           required: true
+          in: path
           type: string
           format: uuid
           description: The id of the asset to be updated
-        closedAt:
+        - name: body
           in: body
-          type: number
-          description: The Unix timestamp when the stream will be or was previously closed.
-        closedMessage:
-          type: string
-          in: body
-          description: The message to display to users when the stream is closed.
-        responses:
-          204:
-            description: Status update successful.
-          500:
-            description: An error has occurred.
+          required: true
+          schema:
+            type: object
+            properties:
+              closedAt:
+                type: number
+                description: The Unix timestamp when the stream will be or was previously closed.
+              closedMessage:
+                type: string
+                description: The message to display to users when the stream is closed.
+      responses:
+        204:
+          description: Status update successful.
+        500:
+          description: An error has occurred.
+          schema:
+            $ref: '#/definitions/Error'
   /stream:
     get:
       tags:
@@ -448,25 +462,22 @@ paths:
             type: object
             properties:
               asset:
-                type: object
-                description: The asset for the url passed to this endpoint.
-                items:
-                  - $ref: '#/definitions/Asset'
+                $ref: '#/definitions/Asset'
               comments:
                 type: array
                 description: All comments for this asset.
                 items:
-                  - $ref: '#/definitions/Comment'
+                  $ref: '#/definitions/Comment'
               users:
                 type: array
                 description: All authors of comments on this asset.
                 items:
-                  - $ref: '#/definitions/User'
+                  $ref: '#/definitions/User'
               actions:
                 type: array
                 description: All actions on comments on this asset and their authors.
                 items:
-                  - $ref: '#/definitions/Actions'
+                  $ref: '#/definitions/Actions'
         500:
           description: An error occured.
           schema:
@@ -483,11 +494,15 @@ paths:
           schema:
             $ref: '#/definitions/Error'
     put:
-      responses:
-        parameteters:
-          body:
+      parameters:
+        - name: body
+          in: body
+          required: true
+          description: Settings to be updated.
+          schema:
             type: object
-            description: Settings to be updated
+            description: Any allowed setting and value.
+      responses:
         204:
           description: The settings were updated.
         500:
@@ -496,99 +511,113 @@ paths:
             $ref: '#/definitions/Error'
   /users:
     get:
-      value:
-        in: query
-        type: string
-        description: A term to search users' displayNames and email addresses.
-      sort:
-        in: query
-        type: string
-        enum:
-          asc
-          desc
-        description: Determines whether users sorted in are ascending or descending order.
-      field:
-        in: query
-        type: string
-        description: The field used to sort.
-      page:
-        in: query
-        type: number
-        description: The page of search results to return.
-      limit:
-        in: query
-        type: number
-        description: The number of search restults per page.
-    responses:
-      200:
-        parameters:
-          result:
-            type: array
-            description: Users matching search criteria.
-            items:
-              $ref: '#/definitions/User'
-          limit:
-            type: number
-            description: Results per page.
-          count:
-            type: number
-            description: Total number of results.
-          page:
-            type: number
-            description: The current page.
-          totalPages:
-            type: number
-            description: The total number of pages.
-      500:
-        description: An error occured.
-        schema:
-          $ref: '#/definitions/Error'
+      parameters:
+       - name: value
+         in: query
+         type: string
+         description: A term to search users' displayNames and email addresses.
+       - name: sort
+         in: query
+         type: string
+         enum:
+          - asc
+          - desc
+         description: Determines whether users sorted in are ascending or descending order.
+       - name: field
+         in: query
+         type: string
+         description: The field used to sort.
+       - name: page
+         in: query
+         type: number
+         description: The page of search results to return.
+       - name: limit
+         in: query
+         type: number
+         description: The number of search restults per page.
+      responses:
+        200:
+          description: A paginated array of users matching search terms.
+          schema:
+            type: object
+            properties:
+              result:
+                type: array
+                description: Users matching search criteria.
+                items:
+                  $ref: '#/definitions/User'
+              limit:
+                type: number
+                description: Results per page.
+              count:
+                type: number
+                description: Total number of results.
+              page:
+                type: number
+                description: The current page.
+              totalPages:
+                type: number
+                description: The total number of pages.
+        500:
+          description: An error occured.
+          schema:
+            $ref: '#/definitions/Error'
     post:
-      body:
-        in: body
-        type: object
-        parameters:
-          email:
-            type: string
-            format: email
-          password:
-            type: string
-          displayName:
-            type: string
+      parameters:
+        - name: body
+          in: body
+          required: true
+          description: User to be created.
+          schema:
+            type: object
+            properties:
+              email:
+                type: string
+                format: email
+              password:
+                type: string
+              displayName:
+                type: string
       responses:
         201:
           description: The user that has been created.
           schema:
             $ref: '#/definitions/User'
-    /users/update-password:
-      post:
-        body:
+  /users/update-password:
+    post:
+      parameters:
+        - name: body
           in: body
-          type: object
-          parameters:
-            token:
-              type: string
-              description: The token that was in the url of the email link.
-            password:
-              type: string
-              description: The new password.
-      response:
+          required: true
+          schema:
+            type: object
+            properties:
+              token:
+                type: string
+                description: The token that was in the url of the email link.
+              password:
+               type: string
+               description: The new password.
+      responses:
         204:
           description: Password update successful.
         500:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
-    /request-password-reset:
-      post:
-        body:
+  /request-password-reset:
+    post:
+      parameters:
+        - name: body
           in: body
-          type: object
-          parameters:
-            email:
-              type: string
-              description: The email address of the user whos password is being reset.
-      response:
+          required: true
+          schema:
+            type: object
+            properties:
+              email:
+                type: string
+                description: The email address of the user whos password is being reset.
+      responses:
         204:
           description: Returned regardless of whether the user was found in the DB.
         500:
@@ -598,21 +627,24 @@ paths:
   /users/{user_id}/role:
     post:
       parameters:
-        user_id:
+        - name: user_id
           in: path
+          required: true
           type: string
           format: uuid
           description: ID of the user to be updated.
-        body:
+        - name: body
           in: body
-          type: object
-          parameters:
-            role:
-              type: string
-              description: Role to be added to the user.
-              enum:
-                admin
-                moderator
+          required: true
+          schema:
+            type: object
+            properties:
+              role:
+                type: string
+                description: Role to be added to the user.
+                enum:
+                  - admin
+                  - moderator
       responses:
         204:
           description: Role update successful.
@@ -622,27 +654,29 @@ paths:
             $ref: '#/definitions/Error'
   /users/{user_id}/status:
     post:
-      user_id:
-        in: path
-        type: string
-        format: uuid
-        required: true
-        description: ID of the user to be updated.
-      body:
-        in: body
-        type: object
-        parameters:
-          status:
-            type: string
-            required: true
-            description: Status for the user to be set to.
-            enum:
-              active
-              banned
-          comment_id:
-            type: string
-            format: uuid
-            description: The id of the comment which triggered this status change.
+      parameters:
+        - name: user_id
+          in: path
+          type: string
+          format: uuid
+          required: true
+          description: ID of the user to be updated.
+        - name: body
+          in: body
+          required: true
+          schema:
+           type: object
+           properties:
+            status:
+              type: string
+              description: Status for the user to be set to.
+              enum:
+                - active
+                - banned
+            comment_id:
+              type: string
+              format: uuid
+              description: The id of the comment which triggered this status change.
       responses:
         200:
           description: Status update successful.
@@ -653,15 +687,21 @@ paths:
   /users/{user_id}/bio:
     put:
       parameters:
-        user_id:
+        - name: user_id
           in: path
+          required: true
           type: string
           format: uuid
           description: The id of the user being updated.
-        bio:
+        - name: body
           in: body
-          type: string
-          description: The bio that should be set for this user.
+          required: true
+          schema:
+            type: object
+            properties:
+              bio:
+                type: string
+                description: The bio that should be set for this user.
       responses:
         200:
           description: Status update successful.
@@ -674,16 +714,26 @@ paths:
   /{user_id}/actions:
     post:
       parameters:
-        - name: action_type
-          in: body
-          description: The type of action being taken on this user.
+        - name: user_id
+          in: path
+          required: true
           type: string
-          enum:
-            - flag
-        - name: metadata
+          format: uuid
+          description: The user on which this action is being taken.
+        - name: body
           in: body
-          type: object
-          description: Arbitrary data to be included with the action.
+          required: true
+          schema:
+            type: object
+            properties:
+              action_type:
+                description: The type of action being taken on this user.
+                type: string
+                enum:
+                  - flag
+              metadata:
+                type: object
+                description: Arbitrary data to be included with the action.
       responses:
         200:
           description: The newly created action.
@@ -693,6 +743,7 @@ paths:
           description: An error occured.
           schema:
             $ref: '#/definitions/Error'
+
 definitions:
   Error:
     type: object