update swagger-jsdoc

apps/app/src/server/models/openapi/page.ts

@@ -11,6 +11,98 @@
  *        description: Grant for page
  *        type: number
  *        example: 1
+ *      PageInfo:
+ *        description: Basic page information
+ *        type: object
+ *        properties:
+ *          isV5Compatible:
+ *            type: boolean
+ *            description: Whether the page is compatible with v5
+ *          isEmpty:
+ *            type: boolean
+ *            description: Whether the page is empty
+ *          isMovable:
+ *            type: boolean
+ *            description: Whether the page is movable
+ *          isDeletable:
+ *            type: boolean
+ *            description: Whether the page is deletable
+ *          isAbleToDeleteCompletely:
+ *            type: boolean
+ *            description: Whether the page is able to delete completely
+ *          isRevertible:
+ *            type: boolean
+ *            description: Whether the page is revertible
+ *      PageInfoForEntity:
+ *        description: Page information for entity (extends IPageInfo)
+ *        allOf:
+ *          - $ref: '#/components/schemas/PageInfo'
+ *          - type: object
+ *            properties:
+ *              bookmarkCount:
+ *                type: number
+ *                description: Number of bookmarks
+ *              sumOfLikers:
+ *                type: number
+ *                description: Number of users who have liked the page
+ *              likerIds:
+ *                type: array
+ *                items:
+ *                  type: string
+ *                description: Ids of users who have liked the page
+ *                example: ["5e07345972560e001761fa63"]
+ *              sumOfSeenUsers:
+ *                type: number
+ *                description: Number of users who have seen the page
+ *              seenUserIds:
+ *                type: array
+ *                items:
+ *                  type: string
+ *                description: Ids of users who have seen the page
+ *                example: ["5e07345972560e001761fa63"]
+ *              contentAge:
+ *                type: number
+ *                description: Content age
+ *              descendantCount:
+ *                type: number
+ *                description: Number of descendant pages
+ *              commentCount:
+ *                type: number
+ *                description: Number of comments
+ *      PageInfoForOperation:
+ *        description: Page information for operation (extends IPageInfoForEntity)
+ *        allOf:
+ *          - $ref: '#/components/schemas/PageInfoForEntity'
+ *          - type: object
+ *            properties:
+ *              isBookmarked:
+ *                type: boolean
+ *                description: Whether the page is bookmarked by the logged in user
+ *              isLiked:
+ *                type: boolean
+ *                description: Whether the page is liked by the logged in user
+ *              subscriptionStatus:
+ *                type: string
+ *                description: Subscription status
+ *                enum:
+ *                  - 'SUBSCRIBE'
+ *                  - 'UNSUBSCRIBE'
+ *      PageInfoForListing:
+ *        description: Page information for listing (extends IPageInfoForEntity with revision short body)
+ *        allOf:
+ *          - $ref: '#/components/schemas/PageInfoForEntity'
+ *          - type: object
+ *            properties:
+ *              revisionShortBody:
+ *                type: string
+ *                description: Short body of the revision
+ *      PageInfoAll:
+ *        description: Page information (union of all page info types)
+ *        oneOf:
+ *          - $ref: '#/components/schemas/PageInfo'
+ *          - $ref: '#/components/schemas/PageInfoForEntity'
+ *          - $ref: '#/components/schemas/PageInfoForOperation'
+ *          - $ref: '#/components/schemas/PageInfoForListing'
  *      Page:
  *        description: Page
  *        type: object

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

@@ -234,16 +234,18 @@ const routerFactory = (crowi: Crowi): Router => {
    *       - bearer: []
    *       - accessTokenInQuery: []
    *     summary: /page-listing/info
-   *     description: Get the information of a page
+   *     description: Get summary information of pages
    *     parameters:
    *       - name: pageIds
    *         in: query
+   *         description: Array of page IDs to retrieve information for (One of pageIds or path is required)
    *         schema:
    *           type: array
    *           items:
    *             type: string
    *       - name: path
    *         in: query
+   *         description: Path of the page to retrieve information for (One of pageIds or path is required)
    *         schema:
    *           type: string
    *       - name: attachBookmarkCount
@@ -261,42 +263,8 @@ const routerFactory = (crowi: Crowi): Router => {
    *           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
+   *               additionalProperties:
+   *                 $ref: '#/components/schemas/PageInfoAll'
    */
   // eslint-disable-next-line max-len
   router.get('/info', accessTokenParser, loginRequired, validator.pageIdsOrPathRequired, validator.infoParams, apiV3FormValidator, async(req: AuthorizedRequest, res: ApiV3Response) => {

apps/app/src/server/routes/apiv3/page/index.ts

@@ -69,47 +69,6 @@ const router = express.Router();
  *            type: boolean
  *            description: boolean for like status
  *
- *      PageInfo:
- *        description: PageInfo
- *        type: object
- *        required:
- *          - sumOfLikers
- *          - likerIds
- *          - sumOfSeenUsers
- *          - seenUserIds
- *        properties:
- *          isLiked:
- *            type: boolean
- *            description: Whether the page is liked by the logged in user
- *          sumOfLikers:
- *            type: number
- *            description: Number of users who have liked the page
- *          likerIds:
- *            type: array
- *            items:
- *              type: string
- *            description: Ids of users who have liked the page
- *            example: ["5e07345972560e001761fa63"]
- *          sumOfSeenUsers:
- *            type: number
- *            description: Number of users who have seen the page
- *          seenUserIds:
- *            type: array
- *            items:
- *              type: string
- *            description: Ids of users who have seen the page
- *            example: ["5e07345972560e001761fa63"]
- *
- *      PageParams:
- *        description: PageParams
- *        type: object
- *        required:
- *          - pageId
- *        properties:
- *          pageId:
- *            type: string
- *            description: page ID
- *            example: 5e07345972560e001761fa63
  */
 /** @param {import('~/server/crowi').default} crowi Crowi instance */
 module.exports = (crowi) => {
@@ -488,20 +447,22 @@ module.exports = (crowi) => {
    *    /page/info:
    *      get:
    *        tags: [Page]
-   *        summary: Get page info
-   *        description: Retrieve current page info
-   *        requestBody:
-   *          content:
-   *            application/json:
-   *              schema:
-   *                $ref: '#/components/schemas/PageParams'
+   *        summary: /page/info
+   *        description: Get summary informations for a page
+   *        parameters:
+   *          - name: pageId
+   *            in: query
+   *            required: true
+   *            description: page id
+   *            schema:
+   *              $ref: '#/components/schemas/ObjectId'
    *        responses:
    *          200:
    *            description: Successfully retrieved current page info.
    *            content:
    *              application/json:
    *                schema:
-   *                  $ref: '#/components/schemas/PageInfo'
+   *                  $ref: '#/components/schemas/PageInfoAll'
    *          500:
    *            description: Internal server error.
    */