Merge pull request #9311 from weseek/imprv/jsdoc-for-openapi

support: JSDoc for OpenAPI document
weseek · Oct 24, 2024 · 2d70d86 · 2d70d86
2 parents 89ac4b9 + 25917c4
commit 2d70d86
Show file tree

Hide file tree

Showing 29 changed files with 147 additions and 225 deletions.
diff --git a/apps/app/bin/swagger-jsdoc/definition-apiv3.js b/apps/app/bin/swagger-jsdoc/definition-apiv3.js
@@ -25,4 +25,69 @@ module.exports = {
       },
     },
   },
+  'x-tagGroups': [
+    {
+      name: 'User API',
+      tags: [
+        'Attachment',
+        'Bookmarks',
+        'Page',
+        'Pages',
+        'Revisions',
+        'ShareLinks',
+        'Users',
+        '',
+        '',
+      ],
+    },
+    {
+      name: 'User Personal Settings API',
+      tags: [
+        'GeneralSetting',
+        'EditorSetting',
+        'InAppNotificationSettings',
+        '',
+        '',
+        '',
+        '',
+        '',
+      ],
+    },
+    {
+      name: 'System Management API',
+      tags: [
+        'Home',
+        'AppSettings',
+        'SecuritySetting',
+        'MarkDownSetting',
+        'CustomizeSetting',
+        'Import',
+        'Export',
+        'MongoDB',
+        'NotificationSetting',
+        'SlackIntegrationSettings',
+        'SlackIntegrationSettings (with proxy)',
+        'SlackIntegrationSettings (without proxy)',
+        'SlackIntegrationLegacySetting',
+        'ShareLink Management',
+        'UserGroupRelations',
+        'UserGroups',
+        'Users Management',
+        'FullTextSearch Management',
+      ],
+    },
+    {
+      name: 'Public API',
+      tags: [
+        'Healthcheck',
+        'Statistics',
+        '',
+        '',
+        '',
+        '',
+        '',
+        '',
+      ],
+    },
+  ],
 };
diff --git a/apps/app/src/server/routes/apiv3/admin-home.js b/apps/app/src/server/routes/apiv3/admin-home.js
@@ -4,12 +4,6 @@ const express = require('express');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: adminHome
- */
-
 /**
  * @swagger
  *
@@ -47,7 +41,7 @@ module.exports = (crowi) => {
    *
    *    /admin-home/:
    *      get:
-   *        tags: [AdminHome]
+   *        tags: [Admin]
    *        operationId: getAdminHome
    *        summary: /admin-home
    *        description: Get adminHome parameters

diff --git a/apps/app/src/server/routes/apiv3/app-settings.js b/apps/app/src/server/routes/apiv3/app-settings.js
@@ -18,12 +18,6 @@ const express = require('express');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: AppSettings
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/attachment.js b/apps/app/src/server/routes/apiv3/attachment.js
@@ -24,13 +24,6 @@ const {
 } = require('express-validator');
 
 
-/**
- * @swagger
- *  tags:
- *    name: Attachment
- */
-
-
 /**
  * @swagger
  *
@@ -231,7 +224,7 @@ module.exports = (crowi) => {
    *
    *    /attachment:
    *      post:
-   *        tags: [Attachment, CrowiCompatibles]
+   *        tags: [Attachment]
    *        operationId: addAttachment
    *        summary: /attachment
    *        description: Add attachment to the page

diff --git a/apps/app/src/server/routes/apiv3/bookmarks.js b/apps/app/src/server/routes/apiv3/bookmarks.js
@@ -17,12 +17,6 @@ const { body, query, param } = require('express-validator');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: Bookmarks
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/customize-setting.js b/apps/app/src/server/routes/apiv3/customize-setting.js
@@ -21,12 +21,6 @@ const logger = loggerFactory('growi:routes:apiv3:customize-setting');
 const router = express.Router();
 
 
-/**
- * @swagger
- *  tags:
- *    name: CustomizeSetting
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/export.js b/apps/app/src/server/routes/apiv3/export.js
@@ -13,12 +13,6 @@ const { param } = require('express-validator');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: Export
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/healthcheck.ts b/apps/app/src/server/routes/apiv3/healthcheck.ts
@@ -13,12 +13,6 @@ const logger = loggerFactory('growi:routes:apiv3:healthcheck');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: Healthcheck
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/import.js b/apps/app/src/server/routes/apiv3/import.js
@@ -17,12 +17,6 @@ const multer = require('multer');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: Import
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/markdown-setting.js b/apps/app/src/server/routes/apiv3/markdown-setting.js
@@ -32,12 +32,6 @@ const validator = {
 };
 
 
-/**
- * @swagger
- *  tags:
- *    name: MarkDownSetting
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/mongo.js b/apps/app/src/server/routes/apiv3/mongo.js
@@ -7,12 +7,6 @@ const mongoose = require('mongoose');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: Mongo
- */
-
 module.exports = (crowi) => {
   const loginRequiredStrictly = require('../../middlewares/login-required')(crowi);
   const adminRequired = require('../../middlewares/admin-required')(crowi);
@@ -22,7 +16,7 @@ module.exports = (crowi) => {
    *
    *  /mongo/collections:
    *    get:
-   *      tags: [Mongo]
+   *      tags: [MongoDB]
    *      operationId: getMongoCollections
    *      summary: /mongo/collections
    *      description: get mongodb collections names

diff --git a/apps/app/src/server/routes/apiv3/notification-setting.js b/apps/app/src/server/routes/apiv3/notification-setting.js
@@ -41,12 +41,6 @@ const validator = {
   ],
 };
 
-/**
- * @swagger
- *  tags:
- *    name: NotificationSetting
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/page/index.ts b/apps/app/src/server/routes/apiv3/page/index.ts
@@ -46,12 +46,6 @@ const { body, query, param } = require('express-validator');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: Page
- */
-
 
 /**
  * @swagger
@@ -671,9 +665,9 @@ module.exports = (crowi) => {
   /**
   * @swagger
   *
-  *    /pages/export:
+  *    /page/export:
   *      get:
-  *        tags: [Export]
+  *        tags: [Page]
   *        description: return page's markdown
   *        responses:
   *          200:

diff --git a/apps/app/src/server/routes/apiv3/pages/index.js b/apps/app/src/server/routes/apiv3/pages/index.js
@@ -27,12 +27,6 @@ const router = express.Router();
 const LIMIT_FOR_LIST = 10;
 const LIMIT_FOR_MULTIPLE_PAGE_OP = 20;
 
-/**
- * @swagger
- *  tags:
- *    name: Pages
- */
-
 /**
  * @swagger
  *

diff --git a/apps/app/src/server/routes/apiv3/personal-setting.js b/apps/app/src/server/routes/apiv3/personal-setting.js
@@ -21,12 +21,6 @@ const passport = require('passport');
 
 const router = express.Router();
 
-/**
- * @swagger
- *  tags:
- *    name: PersonalSetting
- */
-
 /**
  * @swagger
  *
@@ -136,7 +130,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting:
    *      get:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: getPersonalSetting
    *        summary: /personal-setting
    *        description: Get personal parameters
@@ -175,7 +169,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/is-password-set:
    *      get:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: getIsPasswordSet
    *        summary: /personal-setting
    *        description: Get whether a password has been set
@@ -210,7 +204,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting:
    *      put:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: updatePersonalSetting
    *        summary: /personal-setting
    *        description: Update personal setting
@@ -267,7 +261,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/image-type:
    *      put:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: putUserImageType
    *        summary: /personal-setting/image-type
    *        description: Update user image type
@@ -304,7 +298,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/external-accounts:
    *      get:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: getExternalAccounts
    *        summary: /personal-setting/external-accounts
    *        description: Get external accounts that linked current user
@@ -338,7 +332,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/password:
    *      put:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: putUserPassword
    *        summary: /personal-setting/password
    *        description: Update user password
@@ -386,7 +380,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/api-token:
    *      put:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: putUserApiToken
    *        summary: /personal-setting/api-token
    *        description: Update user api token
@@ -424,7 +418,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/associate-ldap:
    *      put:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: associateLdapAccount
    *        summary: /personal-setting/associate-ldap
    *        description: associate Ldap account
@@ -476,7 +470,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/disassociate-ldap:
    *      put:
-   *        tags: [PersonalSetting]
+   *        tags: [GeneralSetting]
    *        operationId: disassociateLdapAccount
    *        summary: /personal-setting/disassociate-ldap
    *        description: disassociate Ldap account
@@ -609,7 +603,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/in-app-notification-settings:
    *      put:
-   *        tags: [in-app-notification-settings]
+   *        tags: [InAppNotificationSettings]
    *        operationId: putInAppNotificationSettings
    *        summary: personal-setting/in-app-notification-settings
    *        description: Put InAppNotificationSettings
@@ -653,7 +647,7 @@ module.exports = (crowi) => {
    *
    *    /personal-setting/in-app-notification-settings:
    *      get:
-   *        tags: [in-app-notification-settings]
+   *        tags: [InAppNotificationSettings]
    *        operationId: getInAppNotificationSettings
    *        summary: personal-setting/in-app-notification-settings
    *        description: Get InAppNotificationSettings
-Original file line number
+Diff line change
@@ Expand Up / @@ -32,12 +32,6 @@ const validator = { @@
     };
-    /**
-     * @swagger
-     *  tags:
-     *    name: MarkDownSetting
-     */
     /**
      * @swagger
      *
@@ Expand Down @@