Merge pull request #9786 from goofmint/fix/doc-v3-page-listing

support(jsdoc): Add swagger document to page-listing.ts

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

@@ -44,6 +44,7 @@ module.exports = {
         'BookmarkFolders',
         'Page',
         'Pages',
+        'PageListing',
         'Revisions',
         'ShareLinks',
         'Users',

apps/app/src/server/routes/apiv3/page-listing.ts

@@ -65,7 +65,27 @@ const routerFactory = (crowi: Crowi): Router => {
 
   const router = express.Router();
 
-
+  /**
+   * @swagger
+   *
+   * /page-listing/root:
+   *   get:
+   *     tags: [PageListing]
+   *     security:
+   *       - api_key: []
+   *     summary: /page-listing/root
+   *     description: Get the root page
+   *     responses:
+   *       200:
+   *         description: Success
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 rootPage:
+   *                   $ref: '#/components/schemas/Page'
+   */
   router.get('/root', accessTokenParser, loginRequired, async(req: AuthorizedRequest, res: ApiV3Response) => {
     const Page = mongoose.model<IPage, PageModel>('Page');
 
@@ -80,6 +100,54 @@ const routerFactory = (crowi: Crowi): Router => {
     return res.apiv3({ rootPage });
   });
 
+  /**
+   * @swagger
+   *
+   * /page-listing/ancestors-children:
+   *   get:
+   *     tags: [PageListing]
+   *     security:
+   *       - api_key: []
+   *     summary: /page-listing/ancestors-children
+   *     description: Get the ancestors and children of a page
+   *     parameters:
+   *       - name: path
+   *         in: query
+   *         required: true
+   *         type: string
+   *     responses:
+   *       200:
+   *         description: Get the ancestors and children of a page
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 ancestorsChildren:
+   *                   type: object
+   *                   additionalProperties:
+   *                     type: object
+   *                     properties:
+   *                       _id:
+   *                         type: string
+   *                         description: Document ID
+   *                       descendantCount:
+   *                         type: integer
+   *                         description: Number of descendants
+   *                       isEmpty:
+   *                         type: boolean
+   *                         description: Indicates if the node is empty
+   *                       grant:
+   *                         type: integer
+   *                         description: Access level
+   *                       path:
+   *                         type: string
+   *                         description: Path string
+   *                       revision:
+   *                         type: string
+   *                         nullable: true
+   *                         description: Revision ID (nullable)
+   */
   // eslint-disable-next-line max-len
   router.get('/ancestors-children', accessTokenParser, loginRequired, ...validator.pagePathRequired, apiV3FormValidator, async(req: AuthorizedRequest, res: ApiV3Response): Promise<any> => {
     const { path } = req.query;
@@ -96,6 +164,36 @@ const routerFactory = (crowi: Crowi): Router => {
 
   });
 
+  /**
+   * @swagger
+   *
+   * /page-listing/children:
+   *   get:
+   *     tags: [PageListing]
+   *     security:
+   *       - api_key: []
+   *     summary: /page-listing/children
+   *     description: Get the children of a page
+   *     parameters:
+   *       - name: id
+   *         in: query
+   *         type: string
+   *       - name: path
+   *         in: query
+   *         type: string
+   *     responses:
+   *       200:
+   *         description: Get the children of a page
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 children:
+   *                   type: array
+   *                   items:
+   *                     $ref: '#/components/schemas/Page'
+   */
   /*
    * In most cases, using id should be prioritized
    */
@@ -120,6 +218,73 @@ const routerFactory = (crowi: Crowi): Router => {
     }
   });
 
+  /**
+   * @swagger
+   *
+   * /page-listing/info:
+   *   get:
+   *     tags: [PageListing]
+   *     security:
+   *       - api_key: []
+   *     summary: /page-listing/info
+   *     description: Get the information of a page
+   *     parameters:
+   *       - name: pageIds
+   *         in: query
+   *         type: array
+   *       - name: path
+   *         in: query
+   *         type: string
+   *       - name: attachBookmarkCount
+   *         in: query
+   *         type: boolean
+   *       - name: attachShortBody
+   *         in: query
+   *         type: boolean
+   *     responses:
+   *       200:
+   *         description: Get the information of a page
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 idToPageInfoMap:
+   *                   type: object
+   *                   additionalProperties:
+   *                     type: object
+   *                     properties:
+   *                       commentCount:
+   *                         type: integer
+   *                       contentAge:
+   *                         type: integer
+   *                       descendantCount:
+   *                         type: integer
+   *                       isAbleToDeleteCompletely:
+   *                         type: boolean
+   *                       isDeletable:
+   *                         type: boolean
+   *                       isEmpty:
+   *                         type: boolean
+   *                       isMovable:
+   *                         type: boolean
+   *                       isRevertible:
+   *                         type: boolean
+   *                       isV5Compatible:
+   *                         type: boolean
+   *                       likerIds:
+   *                         type: array
+   *                         items:
+   *                           type: string
+   *                       seenUserIds:
+   *                         type: array
+   *                         items:
+   *                           type: string
+   *                       sumOfLikers:
+   *                         type: integer
+   *                       sumOfSeenUsers:
+   *                         type: integer
+   */
   // eslint-disable-next-line max-len
   router.get('/info', accessTokenParser, loginRequired, validator.pageIdsOrPathRequired, validator.infoParams, apiV3FormValidator, async(req: AuthorizedRequest, res: ApiV3Response) => {
     const {