Add REST API documentation

In this merge request, the REST API is documented in the Swagger.io format.

backend/src/main/resources/rest/restapi.yaml

+swagger: "2.0"
+info:
+  description: "This page documents the REST API for the Teaching Assistant Management (TAM) platform."
+  version: "1.0.0"
+  title: "Teaching Assistant Management Platform"
+  contact:
+    email: "ta-cs-ewi@tudelft.nl"
+host: "ta.ewi.tudelft.nl"
+basePath: "/api"
+tags:
+  - name: "user"
+    description: "User endpoint"
+  - name: "course"
+    description: "Courses endpoint"
+schemes:
+- "http"
+paths:
+  /user/{userId}:
+    get:
+      tags:
+      - "user"
+      summary: "Find a user by ID"
+      description: "Returns a single user"
+      produces:
+      - "application/json"
+      parameters:
+      - name: "userId"
+        in: "path"
+        description: "ID of user to return"
+        required: true
+        type: "integer"
+        format: "int64"
+      responses:
+        200:
+          description: "Successful operation"
+          schema:
+            $ref: "#/definitions/User"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+    post:
+      tags:
+        - "user"
+      summary: "Update user by ID"
+      description: "Updates and returns the updated user"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "userId"
+          in: "path"
+          description: "ID of user to update"
+          required: true
+          type: "integer"
+          format: "int64"
+        - in: "body"
+          name: "body"
+          description: "User object that has to be updated"
+          required: true
+          schema:
+            $ref: "#/definitions/User"
+      responses:
+        200:
+          description: "Successful operation"
+          schema:
+            $ref: "#/definitions/User"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+    delete:
+      tags:
+        - "user"
+      summary: "Delete user by ID"
+      description: "Removes user with given ID"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "userId"
+          in: "path"
+          description: "ID of user to delete"
+          required: true
+          type: "integer"
+          format: "int64"
+      responses:
+        200:
+          description: "Successful operation"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+
+  /user/{userId}/roles:
+    get:
+      tags:
+        - "user"
+      summary: "Find the roles of an user by given ID of the user"
+      description: "Returns an array of roles"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "userId"
+          in: "path"
+          description: "ID of user to retrieve roles for"
+          required: true
+          type: "integer"
+          format: "int64"
+      responses:
+        200:
+          description: "Successful operation"
+          schema:
+            type: "array"
+            items:
+              $ref: "#/definitions/Role"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+
+  /user/{userId}/gdpr:
+    post:
+      tags:
+        - "user"
+      summary: "Update the GDPR compliance from the user."
+      description: "Notice that this endpoint errors when the GDPR compliance is already set"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "userId"
+          in: "path"
+          description: "ID of user for which the GDPR compliance has to be updated"
+          required: true
+          type: "integer"
+          format: "int64"
+        - in: "body"
+          name: "body"
+          description: "Object that specifies the state of the GDPR compliance"
+          required: true
+          schema:
+            type: "object"
+            properties:
+              gdpr:
+                type: "boolean"
+                example: "true"
+      responses:
+        200:
+          description: "Successful operation"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+
+  /user/{userId}/prerequisites:
+    post:
+      tags:
+        - "user"
+      summary: "Update or create prerequisites"
+      description: "Updates and returns the prerequisites of the given user"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "userId"
+          in: "path"
+          description: "ID of user for which the prerequisites have to be updated"
+          required: true
+          type: "integer"
+          format: "int64"
+        - in: "body"
+          name: "body"
+          description: "Prerequisites object that has to be updated for the given user"
+          required: true
+          schema:
+            $ref: "#/definitions/Prerequisites"
+      responses:
+        200:
+          description: "Successful operation"
+          schema:
+            $ref: "#/definitions/Prerequisites"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+
+  /user/{userId}/upload/englishcert:
+    post:
+      tags:
+      - "user"
+      summary: "Upload the English test certification"
+      description: "Note that the API only supports .pdf file extensions of a size smaller than 3 MB"
+      consumes:
+      - "multipart/form-data"
+      produces:
+      - "application/json"
+      parameters:
+      - name: "userId"
+        in: "path"
+        description: "ID of user for which to upload the English test certification"
+        required: true
+        type: "integer"
+        format: "int64"
+      - name: "certificate"
+        in: "formData"
+        description: "English certificate to upload"
+        required: true
+        type: "file"
+      responses:
+        200:
+          description: "successful operation"
+
+  /user/{userId}/preferences:
+    get:
+      tags:
+        - "user"
+      summary: "Find preferences for given courses"
+      description: "Returns an array of preferences for the given courses. Values of the course ids can be comma seperated."
+      produces:
+        - "application/json"
+      parameters:
+        - name: "userId"
+          in: "path"
+          description: "ID of user for which the preferences are returned"
+          required: true
+          type: "integer"
+          format: "int64"
+        - name: "courses"
+          in: "query"
+          description: "Course IDs that need to be considered for the preferences"
+          required: true
+          type: "array"
+          items:
+            type: "integer"
+            format: "int64"
+          collectionFormat: "multi"
+
+      responses:
+        200:
+          description: "Successful operation"
+          schema:
+            type: "array"
+            items:
+              $ref: "#/definitions/Preference"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+    post:
+      tags:
+        - "user"
+      summary: "Update or create preferences"
+      description: "Updates and returns the prerequisites of the gien user"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "userId"
+          in: "path"
+          description: "ID of user for which the preferences have to be updated"
+          required: true
+          type: "integer"
+          format: "int64"
+        - in: "body"
+          name: "body"
+          description: "Array of objects which represent preferences of the user"
+          required: true
+          schema:
+            type: "array"
+            items:
+              $ref: "#/definitions/Preference"
+      responses:
+        200:
+          description: "Successful operation"
+          schema:
+            type: "array"
+            items:
+              $ref: "#/definitions/Preference"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+    delete:
+      tags:
+        - "user"
+      summary: "Delete preferences for the specified courses and user"
+      description: "Removes preferences of user for the specified courses"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "userId"
+          in: "path"
+          description: "ID of user to delete"
+          required: true
+          type: "integer"
+          format: "int64"
+        - name: "courses"
+          in: "query"
+          description: "Course IDs that need to be considered for the preferences"
+          required: true
+          type: "array"
+          items:
+            type: "integer"
+            format: "int64"
+          collectionFormat: "multi"
+      responses:
+        200:
+          description: "Successful operation"
+        400:
+          description: "Invalid ID supplied"
+        404:
+          description: "User not found"
+
+
+  /course/active:
+    get:
+      tags:
+        - "course"
+      summary: "Find courses which are currently open for preferences"
+      description: "Returns an array of courses"
+      produces:
+        - "application/json"
+      responses:
+        200:
+          description: "successful operation"
+          schema:
+            type: "array"
+            items:
+              $ref: "#/definitions/Course"
+
+
+definitions:
+  Course:
+    type: "object"
+    properties:
+      id:
+        type: "integer"
+        example: 1
+        format: "int64"
+      course_code:
+        type: "string"
+        example: "CSE1100"
+      name:
+        type: "string"
+        example: "Object-oriented Programming"
+      study_year:
+        type: "integer"
+        example: 1
+        format: "int64"
+      teacher:
+        type: "string"
+        example: "Andy Zaidman"
+      owner:
+        type: "integer"
+        example: 2
+        format: "int64"
+      year:
+        type: "integer"
+        example: 2018
+        format: "int64"
+      quarter:
+        type: "integer"
+        example: 1
+        format: "int64"
+  Preference:
+    type: "object"
+    properties:
+      course_id:
+        type: "integer"
+        example: 1
+        format: "int64"
+      last_year:
+        type: "boolean"
+        example: true
+  Prerequisites:
+    type: "object"
+    properties:
+      ta_training:
+        type: "boolean"
+        example: true
+      english_test:
+        type: "boolean"
+        example: true
+  Role:
+    type: "object"
+    properties:
+      id:
+        type: "integer"
+        example: 1
+        format: "int64"
+      name:
+        type: "string"
+        example: "Student"
+  User:
+    type: "object"
+    properties:
+      id:
+        type: "integer"
+        example: 1
+        format: "int64"
+      first_name:
+        type: "string"
+        example: "John"
+      last_name:
+        type: "string"
+        example: "Doe"
+      gender:
+        type: "string"
+        example: "M"
+      netid:
+        type: "string"
+        example: jdoe
+      email:
+        type: "string"
+        example: "J.Doe@email.com"
+      tshirt_size:
+        type: "string"
+        example: "L"
+      gdpr_accepted:
+        type: "boolean"
+        example: true