docs: add api docs to notifications routes

Author: tassiluca

api-service/api/src/real-time/notifications.ts

@@ -7,7 +7,7 @@ const notificationEvent = "new-notification"
 const noticeTime: number = 60_000;
 
 export async function loadAllScheduledNotifications() {
-  // TODO: load all ScheduledNotifications
+  // TODO: load all ScheduledNotifications at server startup
   console.debug("Loading all scheduled notifications")
 }
 
@@ -52,5 +52,5 @@ async function emitNotification(io: Server, event: EventType, body: string) {
     type: event,
     text: body,
   })
-  await notification.save(); // TODO: catch possible errors
+  await notification.save();
 }

api-service/api/src/routes/notifications.route.ts

@@ -16,8 +16,93 @@ const API_LIMITER_RULES: ApiLimiterEntry = {
 
 notificationsRoute.use(apiLimiter(API_LIMITER_RULES, limitStorage));
 
+/**
+ * @openapi
+ *
+ * paths:
+ *   /notifications/all:
+ *      get:
+ *          summary: Return all the notifications for the user
+ *          responses:
+ *              '200':
+ *                  description: Ok
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              allOf:
+ *                                  - $ref: '#/components/schemas/CommonResponse'
+ *              '400':
+ *                  description: Bad Request
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              allOf:
+ *                                  - $ref: '#/components/schemas/BadRequestError'
+ *
+ *              '429':
+ *                  description: Too many requests
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              allOf:
+ *                                  - $ref: '#/components/schemas/TooManyRequestError'
+ *              '500':
+ *                  description: Generic server error
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              allOf:
+ *                                  - $ref: '#/components/schemas/InternalServerError'
+ *
+ */
 notificationsRoute.get("/all", authenticationHandler, getAllNotifications);
 
+/**
+ * @openapi
+ *
+ * paths:
+ *   /notifications/{notificationId}:
+ *      put:
+ *          summary: Mark a notification as read
+ *          parameters:
+ *              - name: notificationId
+ *                in: path
+ *                description: The id of the notification to mark as read
+ *                required: true
+ *                schema:
+ *                    type: string
+ *          responses:
+ *              '201':
+ *                  description: Created
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              allOf:
+ *                                  - $ref: '#/components/schemas/CommonResponse'
+ *              '400':
+ *                  description: Bad Request
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              allOf:
+ *                                  - $ref: '#/components/schemas/BadRequestError'
+ *
+ *              '429':
+ *                  description: Too many requests
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              allOf:
+ *                                  - $ref: '#/components/schemas/TooManyRequestError'
+ *              '500':
+ *                  description: Generic server error
+ *                  content:
+ *                      application/json:
+ *                          schema:
+ *                              allOf:
+ *                                  - $ref: '#/components/schemas/InternalServerError'
+ *
+ */
 notificationsRoute.put("/:notificationId", authenticationHandler, readNotification);
 
 export default notificationsRoute;