Merge pull request #9784 from goofmint/fix/doc-v3-plugins

support(jsdoc): Add swagger document to features/growi-plugin/server/routes/apiv3/admin/index.ts

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

@@ -81,6 +81,7 @@ module.exports = {
         'GROWI to GROWI Transfer',
         'MongoDB',
         'NotificationSetting',
+        'Plugins',
         'QuestionnaireSetting',
         'SlackIntegrationSettings',
         'SlackIntegrationSettings (with proxy)',

apps/app/bin/swagger-jsdoc/generate-spec-apiv3.sh

@@ -11,5 +11,6 @@ swagger-jsdoc \
   -o "${OUT}" \
   -d "${APP_PATH}/bin/swagger-jsdoc/definition-apiv3.js" \
   "${APP_PATH}/src/features/external-user-group/server/routes/apiv3/*.ts" \
+  "${APP_PATH}/src/features/growi-plugin/server/routes/apiv3/**/*.ts" \
   "${APP_PATH}/src/server/routes/apiv3/**/*.{js,ts}" \
   "${APP_PATH}/src/server/models/openapi/**/*.{js,ts}"

apps/app/src/features/growi-plugin/server/routes/apiv3/admin/index.ts

@@ -1,9 +1,10 @@
-import express, { Request, Router } from 'express';
+import type { Request, Router } from 'express';
+import express from 'express';
 import { body, query } from 'express-validator';
 import mongoose from 'mongoose';
 
-import Crowi from '~/server/crowi';
-import { ApiV3Response } from '~/server/routes/apiv3/interfaces/apiv3-response';
+import type Crowi from '~/server/crowi';
+import type { ApiV3Response } from '~/server/routes/apiv3/interfaces/apiv3-response';
 
 import { GrowiPlugin } from '../../../models';
 import { growiPluginService } from '../../../services';
@@ -39,6 +40,45 @@ module.exports = (crowi: Crowi): Router => {
     }
   });
 
+  /**
+   * @swagger
+   *
+   * /plugins:
+   *   post:
+   *     tags: [Plugins]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /plugins
+   *     description: Install a plugin
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             properties:
+   *               pluginInstallerForm:
+   *                 type: object
+   *                 properties:
+   *                   url:
+   *                     type: string
+   *                   ghBranch:
+   *                     type: string
+   *                   ghTag:
+   *                     type: string
+   *     responses:
+   *       200:
+   *         description: OK
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 pluginName:
+   *                   type: string
+   *                   description: The name of the installed plugin
+   *
+   */
   router.post('/', loginRequiredStrictly, adminRequired, validator.pluginFormValueisRequired, async(req: Request, res: ApiV3Response) => {
     const { pluginInstallerForm: formValue } = req.body;
 
@@ -51,6 +91,33 @@ module.exports = (crowi: Crowi): Router => {
     }
   });
 
+  /**
+   * @swagger
+   *
+   * /plugins/{id}/activate:
+   *   put:
+   *     tags: [Plugins]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /plugins/{id}/activate
+   *     description: Activate a plugin
+   *     parameters:
+   *       - name: id
+   *         in: path
+   *         required: true
+   *         type: string
+   *     responses:
+   *       200:
+   *         description: OK
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 pluginName:
+   *                   type: string
+   *                   description: The name of the activated plugin
+   */
   router.put('/:id/activate', loginRequiredStrictly, adminRequired, validator.pluginIdisRequired, async(req: Request, res: ApiV3Response) => {
     const { id } = req.params;
     const pluginId = new ObjectID(id);
@@ -77,6 +144,33 @@ module.exports = (crowi: Crowi): Router => {
     }
   });
 
+  /**
+   * @swagger
+   *
+   * /plugins/{id}/remove:
+   *   delete:
+   *     tags: [Plugins]
+   *     security:
+   *       - cookieAuth: []
+   *     summary: /plugins/{id}/remove
+   *     description: Remove a plugin
+   *     parameters:
+   *       - name: id
+   *         in: path
+   *         required: true
+   *         type: string
+   *     responses:
+   *       200:
+   *         description: OK
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 pluginName:
+   *                   type: string
+   *                   description: The name of the removed plugin
+   */
   router.delete('/:id/remove', loginRequiredStrictly, adminRequired, validator.pluginIdisRequired, async(req: Request, res: ApiV3Response) => {
     const { id } = req.params;
     const pluginId = new ObjectID(id);