From af40ca6601c870d787d04737724739e8acc5b5c6 Mon Sep 17 00:00:00 2001 From: Atsushi Nakatsugawa Date: Fri, 24 Jan 2025 16:30:17 +0900 Subject: [PATCH] support(jsdoc): add swagger document to notification-setting.js --- .../routes/apiv3/notification-setting.js | 168 ++++++++++++++++-- 1 file changed, 149 insertions(+), 19 deletions(-) diff --git a/apps/app/src/server/routes/apiv3/notification-setting.js b/apps/app/src/server/routes/apiv3/notification-setting.js index 22644299722..ea0af680081 100644 --- a/apps/app/src/server/routes/apiv3/notification-setting.js +++ b/apps/app/src/server/routes/apiv3/notification-setting.js @@ -46,6 +46,66 @@ const validator = { * * components: * schemas: + * NotificationParams: + * type: object + * properties: + * isSlackbotConfigured: + * type: boolean + * description: status of slack integration + * isSlackLegacyConfigured: + * type: boolean + * description: status of slack legacy integration + * currentBotType: + * type: string + * description: current bot type + * userNotifications: + * type: array + * items: + * $ref: '#/components/schemas/UserNotification' + * isNotificationForOwnerPageEnabled: + * type: boolean + * description: Whether to notify on owner page + * isNotificationForGroupPageEnabled: + * type: boolean + * description: Whether to notify on group page + * globalNotifications: + * type: array + * items: + * $ref: '#/components/schemas/GlobalNotificationParams' + * description: global notifications + * UserNotification: + * type: object + * properties: + * channel: + * type: string + * description: slack channel name without '#' + * pathPattern: + * type: string + * description: path name of wiki + * createdAt: + * type: string + * description: created date + * creator: + * $ref: '#/components/schemas/User' + * description: user who set notification + * patternPrefix: + * type: string + * description: path pattern prefix + * patternPrefix2: + * type: string + * description: path pattern prefix2 + * provider: + * type: string + * description: provider + * updatedAt: + * type: string + * description: updated date + * __v: + * type: number + * description: version + * _id: + * type: string + * description: id * UserNotificationParams: * type: object * properties: @@ -59,11 +119,37 @@ const validator = { * type: object * properties: * isNotificationForOwnerPageEnabled: - * type: string + * type: boolean * description: Whether to notify on owner page * isNotificationForGroupPageEnabled: - * type: string + * type: boolean * description: Whether to notify on group page + * GlobalNotification: + * type: object + * properties: + * _id: + * type: string + * description: id + * isEnabled: + * type: boolean + * description: is notification enabled + * triggerEvents: + * type: array + * items: + * type: string + * description: trigger events for notify + * __t: + * type: string + * description: type of notification + * slackChannels: + * type: string + * description: channels for notify + * triggerPath: + * type: string + * description: trigger path for notify + * __v: + * type: number + * description: version * GlobalNotificationParams: * type: object * properties: @@ -83,7 +169,7 @@ const validator = { * type: array * items: * type: string - * description: trigger events for notify + * description: trigger events for notify */ module.exports = (crowi) => { const loginRequiredStrictly = require('../../middlewares/login-required')(crowi); @@ -103,6 +189,8 @@ module.exports = (crowi) => { * /notification-setting/: * get: * tags: [NotificationSetting] + * security: + * - cookieAuth: [] * description: Get notification paramators * responses: * 200: @@ -114,6 +202,7 @@ module.exports = (crowi) => { * notificationParams: * type: object * description: notification params + * $ref: '#/components/schemas/NotificationParams' */ router.get('/', loginRequiredStrictly, adminRequired, async(req, res) => { @@ -137,6 +226,8 @@ module.exports = (crowi) => { * /notification-setting/user-notification: * post: * tags: [NotificationSetting] + * security: + * - cookieAuth: [] * description: add user notification setting * requestBody: * required: true @@ -151,12 +242,18 @@ module.exports = (crowi) => { * application/json: * schema: * properties: - * createdUser: - * type: object - * description: user who set notification - * userNotifications: + * responseParams: * type: object - * description: user trigger notifications for updated + * description: response params + * properties: + * createdUser: + * $ref: '#/components/schemas/User' + * description: user who set notification + * userNotifications: + * type: array + * items: + * $ref: '#/components/schemas/UserNotification' + * description: user notification settings */ // eslint-disable-next-line max-len router.post('/user-notification', loginRequiredStrictly, adminRequired, addActivity, validator.userNotification, apiV3FormValidator, async(req, res) => { @@ -188,6 +285,8 @@ module.exports = (crowi) => { * /notification-setting/user-notification/{id}: * delete: * tags: [NotificationSetting] + * security: + * - cookieAuth: [] * description: delete user trigger notification pattern * parameters: * - name: id @@ -202,10 +301,7 @@ module.exports = (crowi) => { * content: * application/json: * schema: - * properties: - * deletedNotificaton: - * type: object - * description: deleted notification + * $ref: '#/components/schemas/UserNotification' */ router.delete('/user-notification/:id', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => { const { id } = req.params; @@ -228,6 +324,32 @@ module.exports = (crowi) => { }); + /** + * @swagger + * + * /notification-setting/global-notification/{id}: + * get: + * tags: [NotificationSetting] + * security: + * - cookieAuth: [] + * description: get global notification setting + * parameters: + * - name: id + * in: path + * required: true + * description: id of global notification + * schema: + * type: string + * responses: + * 200: + * description: Succeeded to get global notification setting + * content: + * application/json: + * schema: + * properties: + * globalNotification: + * $ref: '#/components/schemas/GlobalNotification' + */ router.get('/global-notification/:id', loginRequiredStrictly, adminRequired, validator.globalNotification, async(req, res) => { const notificationSettingId = req.params.id; @@ -251,6 +373,8 @@ module.exports = (crowi) => { * /notification-setting/global-notification: * post: * tags: [NotificationSetting] + * security: + * - cookieAuth: [] * description: add global notification * requestBody: * required: true @@ -268,6 +392,7 @@ module.exports = (crowi) => { * createdNotification: * type: object * description: notification param created + * $ref: '#/components/schemas/GlobalNotification' */ // eslint-disable-next-line max-len router.post('/global-notification', loginRequiredStrictly, adminRequired, addActivity, validator.globalNotification, apiV3FormValidator, async(req, res) => { @@ -336,6 +461,7 @@ module.exports = (crowi) => { * createdNotification: * type: object * description: notification param updated + * $ref: '#/components/schemas/GlobalNotification' */ // eslint-disable-next-line max-len router.put('/global-notification/:id', loginRequiredStrictly, adminRequired, addActivity, validator.globalNotification, apiV3FormValidator, async(req, res) => { @@ -398,6 +524,8 @@ module.exports = (crowi) => { * /notification-setting/notify-for-page-grant: * put: * tags: [NotificationSetting] + * security: + * - cookieAuth: [] * description: Update settings for notify for page grant * requestBody: * required: true @@ -449,6 +577,8 @@ module.exports = (crowi) => { * /notification-setting/global-notification/{id}/enabled: * put: * tags: [NotificationSetting] + * security: + * - cookieAuth: [] * description: toggle enabled global notification * parameters: * - name: id @@ -473,9 +603,9 @@ module.exports = (crowi) => { * application/json: * schema: * properties: - * deletedNotificaton: - * type: object - * description: notification id for updated + * id: + * type: string + * description: notification id */ router.put('/global-notification/:id/enabled', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => { const { id } = req.params; @@ -513,6 +643,8 @@ module.exports = (crowi) => { * /notification-setting/global-notification/{id}: * delete: * tags: [NotificationSetting] + * security: + * - cookieAuth: [] * description: delete global notification pattern * parameters: * - name: id @@ -527,10 +659,8 @@ module.exports = (crowi) => { * content: * application/json: * schema: - * properties: - * deletedNotificaton: - * type: object - * description: deleted notification + * description: deleted notification + * $ref: '#/components/schemas/GlobalNotification' */ router.delete('/global-notification/:id', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => { const { id } = req.params;