Merge pull request #9769 from goofmint/fix/doc-v3-slack-integration

support(jsdoc): add swagger document to slack-integration.js

apps/app/bin/swagger-jsdoc/definition-apiv3.js

@@ -83,6 +83,7 @@ module.exports = {
         'NotificationSetting',
         'Plugins',
         'QuestionnaireSetting',
+        'SlackIntegration',
         'SlackIntegrationSettings',
         'SlackIntegrationSettings (with proxy)',
         'SlackIntegrationSettings (without proxy)',

apps/app/src/server/routes/apiv3/slack-integration.js

@@ -301,6 +301,29 @@ module.exports = (crowi) => {
     return responseUrl;
   }
 
+  /**
+   * @swagger
+   *
+   * /slack-integration/commands:
+   *   post:
+   *     tags: [SlackIntegration]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /slack-integration/commands
+   *     description: Handle Slack commands
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *     responses:
+   *       200:
+   *         description: OK
+   *         schema:
+   *           type: string
+   *           example: "No text."
+   */
   router.post('/commands', addSigningSecretToReq, verifySlackRequest, checkCommandsPermission, async(req, res) => {
     const { body } = req;
     const responseUrl = getResponseUrl(req);
@@ -318,6 +341,36 @@ module.exports = (crowi) => {
   });
 
   // when relation test
+  /**
+   * @swagger
+   *
+   * /slack-integration/proxied/verify:
+   *   post:
+   *     tags: [SlackIntegration]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /slack-integration/proxied/verify
+   *     description: Verify the access token
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               type:
+   *                 type: string
+   *               challenge:
+   *                 type: string
+   *     responses:
+   *       200:
+   *         description: OK
+   *         schema:
+   *           type: object
+   *           properties:
+   *             challenge:
+   *               type: string
+   */
   router.post('/proxied/verify', verifyAccessTokenFromProxy, async(req, res) => {
     const { body } = req;
 
@@ -328,6 +381,29 @@ module.exports = (crowi) => {
     }
   });
 
+  /**
+   * @swagger
+   *
+   * /slack-integration/proxied/commands:
+   *   post:
+   *     tags: [SlackIntegration]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /slack-integration/proxied/commands
+   *     description: Handle Slack commands
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *     responses:
+   *       200:
+   *         description: OK
+   *         schema:
+   *           type: string
+   *           example: "No text."
+   */
   router.post('/proxied/commands', verifyAccessTokenFromProxy, checkCommandsPermission, async(req, res) => {
     const { body } = req;
     const responseUrl = getResponseUrl(req);
@@ -370,17 +446,84 @@ module.exports = (crowi) => {
     }
   }
 
+  /**
+   * @swagger
+   *
+   * /slack-integration/interactions:
+   *   post:
+   *     tags: [SlackIntegration]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /slack-integration/interactions
+   *     description: Handle Slack interactions
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *     responses:
+   *       200:
+   *         description: OK
+   */
   router.post('/interactions', addSigningSecretToReq, verifySlackRequest, parseSlackInteractionRequest, checkInteractionsPermission, async(req, res) => {
     const client = await slackIntegrationService.generateClientForCustomBotWithoutProxy();
     return handleInteractionsRequest(req, res, client);
   });
 
+  /**
+   * @swagger
+   *
+   * /slack-integration/proxied/interactions:
+   *   post:
+   *     tags: [SlackIntegration]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /slack-integration/proxied/interactions
+   *     description: Handle Slack interactions
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *     responses:
+   *       200:
+   *         description: OK
+   */
   router.post('/proxied/interactions', verifyAccessTokenFromProxy, parseSlackInteractionRequest, checkInteractionsPermission, async(req, res) => {
     const tokenPtoG = req.headers['x-growi-ptog-tokens'];
     const client = await slackIntegrationService.generateClientByTokenPtoG(tokenPtoG);
     return handleInteractionsRequest(req, res, client);
   });
 
+  /**
+   * @swagger
+   *
+   * /slack-integration/supported-commands:
+   *   get:
+   *     tags: [SlackIntegration]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /slack-integration/supported-commands
+   *     description: Get supported commands
+   *     responses:
+   *       200:
+   *         description: Supported commands
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 permissionsForBroadcastUseCommands:
+   *                   type: array
+   *                   items:
+   *                     type: object
+   *                 permissionsForSingleUseCommands:
+   *                   type: array
+   *                   items:
+   *                     type: object
+   */
   router.get('/supported-commands', verifyAccessTokenFromProxy, async(req, res) => {
     const tokenPtoG = req.headers['x-growi-ptog-tokens'];
     const slackAppIntegration = await SlackAppIntegration.findOne({ tokenPtoG });
@@ -389,6 +532,31 @@ module.exports = (crowi) => {
     return res.apiv3({ permissionsForBroadcastUseCommands, permissionsForSingleUseCommands });
   });
 
+  /**
+   * @swagger
+   *
+   * /slack-integration/events:
+   *   post:
+   *     tags: [SlackIntegration]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /slack-integration/events
+   *     description: Handle Slack events
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               event:
+   *                 type: object
+   *     responses:
+   *       200:
+   *         description: OK
+   *         schema:
+   *           type: object
+   */
   router.post('/events', verifyUrlMiddleware, addSigningSecretToReq, verifySlackRequest, async(req, res) => {
     const { event } = req.body;
 
@@ -419,6 +587,35 @@ module.exports = (crowi) => {
     ],
   };
 
+  /**
+   * @swagger
+   *
+   * /slack-integration/proxied/events:
+   *   post:
+   *     tags: [SlackIntegration]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /slack-integration/proxied/events
+   *     description: Handle Slack events
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               growiBotEvent:
+   *                 type: object
+   *               data:
+   *                 type: object
+   *     responses:
+   *       200:
+   *         description: OK
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   */
   router.post('/proxied/events', verifyAccessTokenFromProxy, validator.validateEventRequest, async(req, res) => {
     const { growiBotEvent, data } = req.body;