Merge pull request #9586 from goofmint/fix/doc-v3-notification-setting

support(jsdoc): add swagger document to notification-setting.js

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;