Feature/course statistics (#21)

* Add course statistics

* Added teacher info in course statistics

* chore(offering): fix typo and required fields

* added previousYearsToCompare, average grade; splitted teacher name

* chore(offering): fix required fields and average grade per year statistics

---------

Co-authored-by: Luca Pezzolla <[email protected]>

openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Polito Students API
-  version: 1.0.0-ALPHA.58
+  version: 1.0.0-ALPHA.59
 servers:
   - url: https://app.didattica.polito.it/api
     description: Production server (uses live data)
@@ -2527,7 +2527,7 @@ paths:
                   - id: 63775600
                     title: "Nuovo materiale nel corso di Fisica"
                     message: "Nuovo file presentazione.pdf aggiunto al materiale del corso di Fisica"
-                    scope: ["teaching", "courses", "FIS000", "files"]
+                    scope: [ "teaching", "courses", "FIS000", "files" ]
                     isRead: false
         500:
           $ref: '#/components/responses/ErrorResponse'
@@ -2980,6 +2980,36 @@ paths:
         500:
           $ref: '#/components/responses/ErrorResponse'
 
+  /offering/courses/{courseShortcode}/statistics:
+    get:
+      tags:
+        - Offering
+      parameters:
+        - $ref: '#/components/parameters/courseShortcodeParam'
+        - $ref: '#/components/parameters/yearQueryParam'
+        - $ref: '#/components/parameters/teacherIdQueryParam'
+      summary: Retrieve course statistics | Recupera le statistiche dell'insegnamento
+      operationId: getCourseStatistics
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/CourseStatistics'
+                required: [ data ]
+        404:
+          description: Course not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        500:
+          $ref: '#/components/responses/ErrorResponse'
+
   /guides:
     get:
       tags:
@@ -3185,6 +3215,13 @@ components:
       schema:
         type: string
         example: 2022
+    teacherIdQueryParam:
+      name: teacherId
+      in: query
+      required: false
+      schema:
+        type: string
+        example: 1843
   responses:
     ErrorResponse:
       description: Server error
@@ -3434,7 +3471,7 @@ components:
           type: string
           format: date-time
           nullable: false
-      required: [id, examId, courseShortcode, courseName, teacherId, credits, grade, date, state, stateDescription, teacherMessage, isWithdrawn, isFailure, canBeAccepted, canBeRejected, acceptUrl, rejectUrl, confirmedAt, rejectedAt, rejectingExpiresAt]
+      required: [ id, examId, courseShortcode, courseName, teacherId, credits, grade, date, state, stateDescription, teacherMessage, isWithdrawn, isFailure, canBeAccepted, canBeRejected, acceptUrl, rejectUrl, confirmedAt, rejectedAt, rejectingExpiresAt ]
 
     ProvisionalGradeState:
       type: object
@@ -3446,8 +3483,8 @@ components:
           type: string
           example: Provvisorio
         description:
-            type: string
-            example: La valutazione e consolidata. Il docente non ha piu la possibilita di modificarla. Dal momento del consolidamento lo studente ha 48h per esercitare il rifiuto del voto
+          type: string
+          example: La valutazione e consolidata. Il docente non ha piu la possibilita di modificarla. Dal momento del consolidamento lo studente ha 48h per esercitare il rifiuto del voto
       required: [ id, name, description ]
 
     BookingTopicLeaf:
@@ -4069,6 +4106,88 @@ components:
           example: 2022-08-31T14:00:00Z
       required: [ id, type, name, sizeInKiloBytes, mimeType, createdAt ]
 
+    Teacher:
+      type: object
+      properties:
+        id:
+          type: integer
+        firstName:
+          type: string
+        lastName:
+          type: string
+      required: [ id, firstName, lastName ]
+    GradeCount:
+      type: object
+      properties:
+        grade:
+          type: string
+          enum: [ 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 30L ]
+        count:
+          type: integer
+      required: [ grade, count ]
+    YearStatistics:
+      type: object
+      properties:
+        succeeded:
+          type: integer
+        failed:
+          type: integer
+        grades:
+          type: array
+          items:
+            $ref: '#/components/schemas/GradeCount'
+        averageGrade:
+          type: number
+          example: 18.01
+      required: [ succeeded, failed, grades, averageGrade ]
+
+    PreviousYearsToCompare:
+      type: object
+      properties:
+        year:
+          type: integer
+        succeeded:
+          type: integer
+        failed:
+          type: integer
+      required: [ year, succeeded, failed ]
+
+    CourseStatistics:
+      type: object
+      properties:
+        shortcode:
+          type: string
+        year:
+          type: integer
+        teacher:
+          $ref: '#/components/schemas/Teacher'
+        totalEnrolled:
+          type: integer
+        totalSucceeded:
+          type: integer
+        totalFailed:
+          type: integer
+        firstYear:
+          $ref: '#/components/schemas/YearStatistics'
+        secondYear:
+          $ref: '#/components/schemas/YearStatistics'
+        otherYears:
+          $ref: '#/components/schemas/YearStatistics'
+        previousYearsToCompare:
+          type: array
+          items:
+            $ref: '#/components/schemas/PreviousYearsToCompare'
+        years:
+          type: array
+          items:
+            type: integer
+        teachers:
+          type: array
+          items:
+            $ref: '#/components/schemas/Teacher'
+      required: [ shortcode, year, teacher, totalEnrolled, totalSucceeded, totalFailed, firstYear, secondYear, otherYears, previousYearsToCompare, years, teachers ]
+
+
     Exam:
       type: object
       properties:
@@ -4698,7 +4817,7 @@ components:
           description: An array representing the hierarchical path to the object this notification is related to (replicates the navigation/modules structure)
           items:
             type: string
-          example: ["teaching", "courses", "FIS000", "files"]
+          example: [ "teaching", "courses", "FIS000", "files" ]
         sentAt:
           type: string
           format: date-time
@@ -4973,7 +5092,7 @@ components:
             tickets:
               type: boolean
               example: true
-          required: [ notices, files, lectures, bookings, tickets]
+          required: [ notices, files, lectures, bookings, tickets ]
       required: [ data ]
 
     UpdateNotificationPreferencesRequest: