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

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

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

@@ -163,11 +163,39 @@ module.exports = (crowi) => {
    *      get:
    *        tags: [SlackIntegrationSettings]
    *        operationId: getSlackBotSettingParams
-   *        summary: /slack-integration
+   *        summary: /slack-integration-settings
    *        description: Get current settings and connection statuses.
    *        responses:
    *          200:
    *            description: Succeeded to get info.
+   *            content:
+   *              application/json:
+   *                properties:
+   *                  currentBotType:
+   *                    type: string
+   *                  settings:
+   *                    type: object
+   *                    properties:
+   *                      slackSigningSecretEnvVars:
+   *                        type: string
+   *                      slackBotTokenEnvVars:
+   *                        type: string
+   *                      slackSigningSecret:
+   *                        type: string
+   *                      slackBotToken:
+   *                        type: string
+   *                      commandPermission:
+   *                        type: object
+   *                      eventActionsPermission:
+   *                        type: object
+   *                      proxyServerUri:
+   *                        type: string
+   *                  connectionStatuses:
+   *                    type: object
+   *                  errorMsg:
+   *                    type: string
+   *                  errorCode:
+   *                    type: string
    */
   router.get('/', accessTokenParser, loginRequiredStrictly, adminRequired, async(req, res) => {
 
@@ -361,9 +389,21 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/without-proxy/update-settings/:
    *      put:
    *        tags: [SlackIntegrationSettings (without proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: putWithoutProxySettings
-   *        summary: update customBotWithoutProxy settings
+   *        summary: /slack-integration-settings/without-proxy/update-settings
    *        description: Update customBotWithoutProxy setting.
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  slackSigningSecret:
+   *                    type: string
+   *                  slackBotToken:
+   *                    type: string
    *        responses:
    *           200:
    *             description: Succeeded to put CustomBotWithoutProxy setting.
@@ -401,9 +441,21 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/without-proxy/update-permissions/:
    *      put:
    *        tags: [SlackIntegrationSettings (without proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: putWithoutProxyPermissions
-   *        summary: update customBotWithoutProxy permissions
+   *        summary: /slack-integration-settings/without-proxy/update-permissions
    *        description: Update customBotWithoutProxy permissions.
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  commandPermission:
+   *                    type: object
+   *                  eventActionsPermission:
+   *                    type: object
    *        responses:
    *           200:
    *             description: Succeeded to put CustomBotWithoutProxy permissions.
@@ -444,12 +496,29 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/slack-app-integrations:
    *      post:
    *        tags: [SlackIntegrationSettings (with proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: putSlackAppIntegrations
-   *        summary: /slack-integration
+   *        summary: /slack-integration-settings/slack-app-integrations
    *        description: Generate SlackAppIntegrations
    *        responses:
    *          200:
    *            description: Succeeded to create slack app integration
+   *            content:
+   *              application/json:
+   *                properties:
+   *                  tokenGtoP:
+   *                    type: string
+   *                  tokenPtoG:
+   *                    type: string
+   *                  permissionsForBroadcastUseCommands:
+   *                    type: object
+   *                  permissionsForSingleUseCommands:
+   *                    type: object
+   *                  permissionsForSlackEvents:
+   *                    type: object
+   *                  isPrimary:
+   *                    type: boolean
    */
   router.post('/slack-app-integrations', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => {
     const SlackAppIntegrationRecordsNum = await SlackAppIntegration.countDocuments();
@@ -494,12 +563,25 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/slack-app-integrations/:id:
    *      delete:
    *        tags: [SlackIntegrationSettings (with proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: deleteAccessTokens
-   *        summary: delete accessTokens
+   *        summary: /slack-integration-settings/slack-app-integrations/:id
    *        description: Delete accessTokens
+   *        parameters:
+   *          - name: id
+   *            in: path
+   *            required: true
+   *            schema:
+   *              type: string
    *        responses:
    *          200:
    *            description: Succeeded to delete access tokens for slack
+   *            content:
+   *              application/json:
+   *                properties:
+   *                  response:
+   *                    type: object
    */
   router.delete('/slack-app-integrations/:id', loginRequiredStrictly, adminRequired, validator.deleteIntegration, apiV3FormValidator, addActivity,
     async(req, res) => {
@@ -525,6 +607,32 @@ module.exports = (crowi) => {
       }
     });
 
+  /**
+   * @swagger
+   *   /slack-integration-settings/proxy-uri:
+   *     put:
+   *       tags: [SlackIntegrationSettings (with proxy)]
+   *       security:
+   *         - cookieAuth: []
+   *       operationId: putProxyUri
+   *       summary: /slack-integration-settings/proxy-uri
+   *       description: Update proxy uri
+   *       requestBody:
+   *         required: true
+   *         content:
+   *           application/json:
+   *             schema:
+   *               properties:
+   *                 proxyUri:
+   *                   type: string
+   *       responses:
+   *         200:
+   *           description: Succeeded to update proxy uri
+   *           content:
+   *             application/json:
+   *               schema:
+   *                 type: object
+   */
   router.put('/proxy-uri', loginRequiredStrictly, adminRequired, addActivity, validator.proxyUri, apiV3FormValidator, async(req, res) => {
     const { proxyUri } = req.body;
 
@@ -552,9 +660,17 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/slack-app-integrations/:id/makeprimary:
    *      put:
    *        tags: [SlackIntegrationSettings (with proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: makePrimary
-   *        summary: /slack-integration
+   *        summary: /slack-integration-settings/slack-app-integrations/:id/makeprimary
    *        description: Make SlackAppTokens primary
+   *        parameters:
+   *          - name: id
+   *            in: path
+   *            required: true
+   *            schema:
+   *              type: string
    *        responses:
    *          200:
    *            description: Succeeded to make it primary
@@ -599,12 +715,24 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/slack-app-integrations/:id/regenerate-tokens:
    *      put:
    *        tags: [SlackIntegrationSettings (with proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: putRegenerateTokens
-   *        summary: /slack-integration
+   *        summary: /slack-integration-settings/slack-app-integrations/:id/regenerate-tokens
    *        description: Regenerate SlackAppTokens
+   *        parameters:
+   *          - name: id
+   *            in: path
+   *            required: true
+   *            schema:
+   *              type: string
    *        responses:
    *          200:
    *            description: Succeeded to regenerate slack app tokens
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  type: object
    */
   // eslint-disable-next-line max-len
   router.put('/slack-app-integrations/:id/regenerate-tokens', loginRequiredStrictly, adminRequired, addActivity, validator.regenerateTokens, apiV3FormValidator, async(req, res) => {
@@ -632,12 +760,36 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/slack-app-integrations/:id/permissions:
    *      put:
    *        tags: [SlackIntegrationSettings (with proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: putSupportedCommands
-   *        summary: /slack-integration-settings/:id/permissions
+   *        summary: /slack-integration-settings/slack-app-integrations/:id/permissions
    *        description: update supported commands
+   *        parameters:
+   *          - name: id
+   *            in: path
+   *            required: true
+   *            schema:
+   *              type: string
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  permissionsForBroadcastUseCommands:
+   *                    type: object
+   *                  permissionsForSingleUseCommands:
+   *                    type: object
+   *                  permissionsForSlackEventActions:
+   *                    type: object
    *        responses:
    *          200:
    *            description: Succeeded to update supported commands
+   *            content:
+   *              application/json:
+   *                schema:
+   *                  type: object
    */
   // eslint-disable-next-line max-len
   router.put('/slack-app-integrations/:id/permissions', loginRequiredStrictly, adminRequired, addActivity, validator.updatePermissionsWithProxy, apiV3FormValidator, async(req, res) => {
@@ -691,9 +843,25 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/slack-app-integrations/:id/relation-test:
    *      post:
    *        tags: [SlackIntegrationSettings (with proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: postRelationTest
-   *        summary: Test relation
+   *        summary: /slack-integration-settings/slack-app-integrations/:id/relation-test
    *        description: Delete botType setting.
+   *        parameters:
+   *          - name: id
+   *            in: path
+   *            required: true
+   *            schema:
+   *              type: string
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  channel:
+   *                    type: string
    *        responses:
    *           200:
    *             description: Succeeded to delete botType setting.
@@ -762,15 +930,17 @@ module.exports = (crowi) => {
    *    /slack-integration-settings/without-proxy/test:
    *      post:
    *        tags: [SlackIntegrationSettings (without proxy)]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: postTest
-   *        summary: test the connection
+   *        summary: /slack-integration-settings/without-proxy/test
    *        description: Test the connection with slack work space.
    *        requestBody:
    *          content:
    *            application/json:
    *              schema:
    *                properties:
-   *                  testChannel:
+   *                  channel:
    *                    type: string
    *        responses:
    *           200: