Merge pull request #33 from 5-Bits-in-a-Byte/api-docs

Api docs

server/flasgger/comments.yml

@@ -0,0 +1,47 @@
+Comment:
+  type: object
+  description: Comment on a post
+  properties:
+    post_id:
+      required: true
+      type: string
+      description: Id of the parent post
+      example: abcde12345
+    content:
+      required: true
+      type: string
+      description: Comment content
+      example: I also have that question!
+    postedby:
+      required: true
+      $ref: "#/definitions/PostedBy"
+    endorsed:
+      required: true
+      type: boolean
+      description: If the instructor endorsed this comment
+      default: false
+      example: true
+    replies:
+      required: true
+      type: array
+      items:
+        $ref: "#/definitions/Reply"
+    reactions:
+      required: true
+      $ref: "#/definitions/Reactions"
+
+CommentBody:
+  type: object
+  description: A new comment sent from a client
+  properties:
+    content:
+      required: true
+      type: string
+      description: Comment content
+      example: I also have that question!
+    isAnonymous:
+      required: true
+      type: boolean
+      description: If the user wants the comment to be anonymous
+      default: false
+      example: true

server/flasgger/posts.yml

@@ -0,0 +1,57 @@
+Post:
+  type: object
+  description: Posts with content created by users
+  properties:
+    _id:
+      type: string
+      description: Id of the user who created the post
+      example: abcde12345
+    courseid:
+      type: string
+      description: Id of the course the post was created in
+      example: oFAeuzdT4VwKf3dHUFGhwu
+    postedby:
+      $ref: "#/definitions/PostedBy"
+    title:
+      type: string
+      description: Title of the post
+      example: Question about homework 3?
+    content:
+      type: string
+      description: Content of the post
+      example: This homework doesn't make any sense to me. What chapters does this cover in the book?
+    isInstructor:
+      type: boolean
+      default: false
+      description: Whether or not the post was created by an instructor
+      example: false
+    isPinned:
+      type: boolean
+      default: false
+      description: Whether or not the post is pinned
+      example: false
+    isPrivate:
+      type: boolean
+      default: false
+      description: Whether or not the post is private
+      example: false
+    instructorCommented:
+      type: boolean
+      default: false
+      description: Whether or not the instructor has responded to the post
+      example: false
+    reactions:
+      $ref: "#/definitions/Reactions"
+    comments:
+      type: integer
+      description: Number of comments on the post
+      default: 0
+      example: 3
+    createdDate:
+      type: string
+      description: Date the post was created
+      example: 2021-03-12 20:40:00.752000
+    updatedDate:
+      type: string
+      description: Date the post was was last responded to or modified
+      example: 2021-03-13 21:20:00.322000

server/flasgger/replies.yml

@@ -0,0 +1,36 @@
+Reply:
+  type: object
+  description: Reply to a comment
+  properties:
+    _id:
+      type: string
+      required: true
+      description: Reply ID
+      example: ofjaepwofj324
+    content:
+      type: string
+      required: true
+      description: Comment content
+      example: That is a great comment. Wow!
+    postedby:
+      required: true
+      $ref: "#/definitions/PostedBy"
+    reactions:
+      required: true
+      $ref: "#/definitions/Reactions"
+
+ReplyBody:
+  type: object
+  description: A new reply sent from a client
+  properties:
+    content:
+      required: true
+      type: string
+      description: Reply content
+      example: That's a great comment!
+    isAnonymous:
+      required: true
+      type: boolean
+      description: If the user wants the reply to be anonymous
+      default: false
+      example: true

server/flasgger/requests.yml

@@ -0,0 +1,21 @@
+POSTPostBody:
+  type: object
+  properties:
+    title:
+      type: string
+      description: Title of post
+      example: Question about homework 3?
+    content:
+      type: string
+      description: Content of the post
+      example: This homework doesn't make any sense to me. What chapters does this cover in the book?
+    isPrivate:
+      type: boolean
+      default: false
+      description: Whether or not the post is private
+      example: false
+    isAnonymous:
+      type: boolean
+      default: false
+      description: Whether or not the post is anonymous
+      example: false

server/flasgger/responses.yml

@@ -0,0 +1,19 @@
+400Response:
+  type: object
+  description: Response to bad requests
+  properties:
+    errors:
+      type: list
+      description: List of errors related to failed request
+      example: ["Invalid courseid"]
+403Response:
+  type: object
+  description: Response to unauthorized requests
+  properties:
+    errors:
+      type: list
+      description: List of authorization errors
+      example:
+        [
+          "Resource access restricted: missing course permission(s) admin, seePrivate",
+        ]

server/flasgger/shared.yml

@@ -0,0 +1,33 @@
+Reactions:
+  type: object
+  description: Reaction types with arrays of _ids of the users who reacted
+  properties:
+    likes:
+      type: list
+      description: List of users who have liked the content
+      example: ["abcde12345"]
+PostedBy:
+  type: object
+  description: Information about the user who posted the content
+  properties:
+    first:
+      type: string
+      description: First name of the user who posted the content
+      example: Alec
+    last:
+      type: string
+      description: Last name of the user who posted the content
+      example: Springel
+    _id:
+      type: string
+      description: _id or anonymousId of user who posted the content
+      example: abcde12345
+    anonymous:
+      type: boolean
+      default: false
+      description: Whether or not the content is posted anonymously
+      example: false
+    picture:
+      type: string
+      description: Profile photo URL
+      example: "https://google.com/user123/photo123"

server/flasgger/user.yml

@@ -0,0 +1,85 @@
+User:
+  type: object
+  properties:
+    _id:
+      type: string
+      description: Unique user identifier
+      example: abcde12345
+    anonymousId:
+      type: string
+      description: Secondary unique user identifier
+      example: d1e2f3g4h5
+    email:
+      type: string
+      description: Email address
+      example: cyrilfiggis@gmail.com
+    first:
+      type: string
+      description: First name
+      example: Cyril
+    last:
+      type: string
+      description: Last name
+      example: Figgis
+    picture:
+      type: string
+      description: URL of the user's avatar picture
+      example: https://avatars.githubusercontent.com/u/111111111?v=4
+    courses:
+      type: array
+      items:
+        $ref: "#/definitions/UserCourse"
+UserCourse:
+  type: object
+  properties:
+    course_id:
+      type: string
+      description: ID of the course the user joined
+      example: vytxeTZskVKR7C7WgdSP3d
+    course_name:
+      type: string
+      description: Name associated with the course
+      example: "CIS499 Advanced Debugging"
+    nickname:
+      type: string
+      description: Course nickname
+      example: "CIS499"
+    color:
+      type: string
+      description: Accent color used in course specific ui
+      example: "#ee55ee"
+    canPost:
+      type: boolean
+      description: If the user can post in the course
+      default: true
+      example: true
+    seePrivate:
+      type: boolean
+      description: If the user can see private posts in the course
+      default: false
+      example: false
+    canPin:
+      type: boolean
+      description: If the user user can pin posts
+      default: false
+      example: false
+    canRemove:
+      type: boolean
+      description: If the user can remove posts from the course
+      default: false
+      example: false
+    canEndorse:
+      type: boolean
+      description: If the user can endorse posts in the course
+      default: false
+      example: true
+    viewAnonymous:
+      type: boolean
+      description: If the user can view the identity of anonymous posters
+      default: false
+      example: true
+    admin:
+      type: boolean
+      description: If the user is an administrator of the course
+      default: false
+      example: false