Merge pull request #9525 from goofmint/fix/doc-v3-in-app-notification

support(jsdoc): add swagger document to in-app-notification.ts

apps/app/src/server/routes/apiv3/in-app-notification.ts

@@ -13,6 +13,78 @@ import type { ApiV3Response } from './interfaces/apiv3-response';
 
 const router = express.Router();
 
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     InAppNotificationListResponse:
+ *       type: object
+ *       properties:
+ *         docs:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/InAppNotificationDocument'
+ *         totalDocs:
+ *           type: integer
+ *           description: Total number of in app notification documents
+ *         offset:
+ *           type: integer
+ *           description: Offset value
+ *         limit:
+ *           type: integer
+ *           description: Limit per page
+ *         totalPages:
+ *           type: integer
+ *           description: Total pages available
+ *         page:
+ *           type: integer
+ *           description: Current page number
+ *         hasPrevPage:
+ *           type: boolean
+ *           description: Indicator for previous page
+ *         hasNextPage:
+ *           type: boolean
+ *           description: Indicator for next page
+ *         prevPage:
+ *           type: string
+ *           description: Previous page number or null
+ *         nextPage:
+ *           type: string
+ *           description: Next page number or null
+ *     InAppNotificationDocument:
+ *       type: object
+ *       properties:
+ *         _id:
+ *           type: string
+ *           description: In app notification document ID
+ *         action:
+ *           type: string
+ *           description: Action performed on the in app notification document
+ *         snapshot:
+ *           type: string
+ *           description: Snapshot details in JSON format
+ *         target:
+ *           $ref: '#/components/schemas/Page'
+ *         user:
+ *           $ref: '#/components/schemas/User'
+ *         createdAt:
+ *           type: string
+ *           format: date-time
+ *           description: Creation timestamp
+ *         status:
+ *           type: string
+ *           description: Status of the in app notification document
+ *         targetModel:
+ *           type: string
+ *           description: Model of the target
+ *         id:
+ *           type: string
+ *           description: In app notification document ID
+ *         actionUsers:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/User'
+ */
 /** @param {import('~/server/crowi').default} crowi Crowi instance */
 module.exports = (crowi) => {
   const loginRequiredStrictly = require('../../middlewares/login-required')(crowi);
@@ -24,6 +96,41 @@ module.exports = (crowi) => {
 
   const activityEvent = crowi.event('activity');
 
+  /**
+   * @swagger
+   *
+   *  /in-app-notification/list:
+   *    get:
+   *      tags: [NotificationSetting]
+   *      security:
+   *        - api_key: []
+   *      operationId: getInAppNotificationList
+   *      summary: /in-app-notification/list
+   *      description: Get the list of in-app notifications
+   *      parameters:
+   *        - name: limit
+   *          in: query
+   *          description: The number of notifications to get
+   *          schema:
+   *            type: integer
+   *        - name: offset
+   *          in: query
+   *          description: The number of notifications to skip
+   *          schema:
+   *            type: integer
+   *        - name: status
+   *          in: query
+   *          description: The status to categorize. 'UNOPENED' or 'OPENED'.
+   *          schema:
+   *            type: string
+   *      responses:
+   *        200:
+   *          description: The list of in-app notifications
+   *          content:
+   *            application/json:
+   *              schema:
+   *                $ref: '#/components/schemas/InAppNotificationListResponse'
+   */
   router.get('/list', accessTokenParser, loginRequiredStrictly, async(req: CrowiRequest, res: ApiV3Response) => {
     // user must be set by loginRequiredStrictly
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -79,6 +186,28 @@ module.exports = (crowi) => {
     return res.apiv3(serializedPaginationResult);
   });
 
+  /**
+   * @swagger
+   *
+   *  /in-app-notification/status:
+   *    get:
+   *      tags: [NotificationSetting]
+   *      security:
+   *        - api_key: []
+   *      operationId: getInAppNotificationStatus
+   *      summary: /in-app-notification/status
+   *      description: Get the status of in-app notifications
+   *      responses:
+   *        200:
+   *          description: Get count of unread notifications
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  count:
+   *                    type: integer
+   *                    description: Count of unread notifications
+   */
   router.get('/status', accessTokenParser, loginRequiredStrictly, async(req: CrowiRequest, res: ApiV3Response) => {
     // user must be set by loginRequiredStrictly
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -93,6 +222,35 @@ module.exports = (crowi) => {
     }
   });
 
+  /**
+   * @swagger
+   *
+   *  /in-app-notification/open:
+   *    post:
+   *      tags: [NotificationSetting]
+   *      security:
+   *        - api_key: []
+   *      operationId: openInAppNotification
+   *      summary: /in-app-notification/open
+   *      description: Open the in-app notification
+   *      requestBody:
+   *        content:
+   *          application/json:
+   *            schema:
+   *              properties:
+   *                id:
+   *                  type: string
+   *                  description: Notification ID
+   *              required:
+   *                - id
+   *      responses:
+   *        200:
+   *          description: Notification opened successfully
+   *          content:
+   *            application/json:
+   *              schema:
+   *                type: object
+   */
   router.post('/open', accessTokenParser, loginRequiredStrictly, async(req: CrowiRequest, res: ApiV3Response) => {
     // user must be set by loginRequiredStrictly
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -110,6 +268,21 @@ module.exports = (crowi) => {
     }
   });
 
+  /**
+   * @swagger
+   *
+   *  /in-app-notification/all-statuses-open:
+   *    put:
+   *      tags: [NotificationSetting]
+   *      security:
+   *        - api_key: []
+   *      operationId: openAllInAppNotification
+   *      summary: /in-app-notification/all-statuses-open
+   *      description: Open all in-app notifications
+   *      responses:
+   *        200:
+   *          description: All notifications opened successfully
+   */
   router.put('/all-statuses-open', accessTokenParser, loginRequiredStrictly, addActivity, async(req: CrowiRequest, res: ApiV3Response) => {
     // user must be set by loginRequiredStrictly
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion