Merge pull request #9740 from goofmint/fix/doc-v3-user-group

support(jsdoc): add swagger document to user-group.js

apps/app/src/server/routes/apiv3/user-group.js

@@ -89,9 +89,36 @@ module.exports = (crowi) => {
    *    /user-groups:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getUserGroup
    *        summary: /user-groups
    *        description: Get usergroups
+   *        parameters:
+   *          - name: page
+   *            in: query
+   *            required: false
+   *            description: page number
+   *            schema:
+   *              type: number
+   *          - name: limit
+   *            in: query
+   *            required: false
+   *            description: number of items per page
+   *            schema:
+   *              type: number
+   *          - name: offset
+   *            in: query
+   *            required: false
+   *            description: offset
+   *            schema:
+   *              type: number
+   *          - name: pagination
+   *            in: query
+   *            required: false
+   *            description: whether to paginate
+   *            schema:
+   *              type: boolean
    *        responses:
    *          200:
    *            description: usergroups are fetched
@@ -102,6 +129,12 @@ module.exports = (crowi) => {
    *                    userGroups:
    *                      type: object
    *                      description: a result of `UserGroup.find`
+   *                    totalUserGroups:
+   *                      type: number
+   *                      description: the number of userGroups
+   *                    pagingLimit:
+   *                      type: number
+   *                      description: the number of items per page
    */
   router.get('/', loginRequiredStrictly, adminRequired, async(req, res) => {
     const { query } = req;
@@ -129,11 +162,13 @@ module.exports = (crowi) => {
    * @swagger
    *
    *  paths:
-   *    /ancestors:
+   *    /user-groups/ancestors:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getAncestorUserGroups
-   *        summary: /ancestors
+   *        summary: /user-groups/ancestors
    *        description: Get ancestor user groups.
    *        parameters:
    *          - name: groupId
@@ -149,7 +184,7 @@ module.exports = (crowi) => {
    *              application/json:
    *                schema:
    *                  properties:
-   *                    userGroups:
+   *                    ancestorUserGroups:
    *                      type: array
    *                      items:
    *                        type: object
@@ -170,6 +205,50 @@ module.exports = (crowi) => {
     }
   });
 
+  /**
+   * @swagger
+   *    paths:
+   *      /user-groups/children:
+   *        get:
+   *          tags: [UserGroups]
+   *          security:
+   *            - cookieAuth: []
+   *          operationId: getUserGroupChildren
+   *          summary: /user-groups/children
+   *          description: Get child user groups
+   *          parameters:
+   *            - name: parentIds
+   *              in: query
+   *              required: false
+   *              description: IDs of parent user groups
+   *              schema:
+   *                type: array
+   *                items:
+   *                  type: string
+   *            - name: includeGrandChildren
+   *              in: query
+   *              required: false
+   *              description: Whether to include grandchild user groups
+   *              schema:
+   *                type: boolean
+   *          responses:
+   *            200:
+   *              description: Child user groups are fetched
+   *              content:
+   *                application/json:
+   *                  schema:
+   *                    properties:
+   *                      childUserGroups:
+   *                        type: array
+   *                        items:
+   *                          type: object
+   *                        description: Child user group objects
+   *                      grandChildUserGroups:
+   *                        type: array
+   *                        items:
+   *                          type: object
+   *                        description: Grandchild user group objects
+   */
   router.get('/children', loginRequiredStrictly, adminRequired, validator.listChildren, async(req, res) => {
     try {
       const { parentIds, includeGrandChildren = false } = req.query;
@@ -195,6 +274,8 @@ module.exports = (crowi) => {
    *    /user-groups:
    *      post:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: createUserGroup
    *        summary: /user-groups
    *        description: Adds userGroup
@@ -207,6 +288,12 @@ module.exports = (crowi) => {
    *                  name:
    *                    type: string
    *                    description: name of the userGroup trying to be added
+   *                  description:
+   *                    type: string
+   *                    description: description of the userGroup trying to be added
+   *                  parentId:
+   *                    type: string
+   *                    description: parentId of the userGroup trying to be added
    *        responses:
    *          200:
    *            description: userGroup is added
@@ -245,6 +332,8 @@ module.exports = (crowi) => {
    *    /selectable-parent-groups:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getSelectableParentGroups
    *        summary: /selectable-parent-groups
    *        description: Get selectable parent UserGroups
@@ -262,7 +351,7 @@ module.exports = (crowi) => {
    *              application/json:
    *                schema:
    *                  properties:
-   *                    userGroups:
+   *                    selectableParentGroups:
    *                      type: array
    *                      items:
    *                        type: object
@@ -294,6 +383,8 @@ module.exports = (crowi) => {
    *    /selectable-child-groups:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getSelectableChildGroups
    *        summary: /selectable-child-groups
    *        description: Get selectable child UserGroups
@@ -311,7 +402,7 @@ module.exports = (crowi) => {
    *              application/json:
    *                schema:
    *                  properties:
-   *                    userGroups:
+   *                    selectableChildGroups:
    *                      type: array
    *                      items:
    *                        type: object
@@ -346,6 +437,8 @@ module.exports = (crowi) => {
    *    /user-groups/{id}:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getUserGroupFromGroupId
    *        summary: /user-groups/{id}
    *        description: Get UserGroup from Group ID
@@ -388,6 +481,8 @@ module.exports = (crowi) => {
    *    /user-groups/{id}:
    *      delete:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: deleteUserGroup
    *        summary: /user-groups/{id}
    *        description: Deletes userGroup
@@ -408,6 +503,11 @@ module.exports = (crowi) => {
    *            description: userGroup id that will be transferred to
    *            schema:
    *              type: string
+   *          - name: transferToUserGroupType
+   *            in: query
+   *            description: userGroup type that will be transferred to
+   *            schema:
+   *              type: string
    *        responses:
    *          200:
    *            description: userGroup is removed
@@ -452,6 +552,8 @@ module.exports = (crowi) => {
    *    /user-groups/{id}:
    *      put:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: updateUserGroups
    *        summary: /user-groups/{id}
    *        description: Update userGroup
@@ -462,6 +564,24 @@ module.exports = (crowi) => {
    *            description: id of userGroup
    *            schema:
    *              type: string
+   *        requestBody:
+   *          required: true
+   *          content:
+   *            application/json:
+   *              schema:
+   *                properties:
+   *                  name:
+   *                    type: string
+   *                    description: name of the userGroup trying to be updated
+   *                  description:
+   *                    type: string
+   *                    description: description of the userGroup trying to be updated
+   *                  parentId:
+   *                    type: string
+   *                    description: parentId of the userGroup trying to be updated
+   *                  forceUpdateParents:
+   *                    type: boolean
+   *                    description: whether to update parent groups
    *        responses:
    *          200:
    *            description: userGroup is updated
@@ -502,6 +622,8 @@ module.exports = (crowi) => {
    *    /user-groups/{id}/users:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getUsersUserGroups
    *        summary: /user-groups/{id}/users
    *        description: Get users related to the userGroup
@@ -522,7 +644,7 @@ module.exports = (crowi) => {
    *                    users:
    *                      type: array
    *                      items:
-   *                        type: object
+   *                        $ref: '#/components/schemas/User'
    *                      description: user objects
    */
   router.get('/:id/users', loginRequiredStrictly, adminRequired, async(req, res) => {
@@ -553,6 +675,8 @@ module.exports = (crowi) => {
    *    /user-groups/{id}/unrelated-users:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getUnrelatedUsersUserGroups
    *        summary: /user-groups/{id}/unrelated-users
    *        description: Get users unrelated to the userGroup
@@ -563,6 +687,26 @@ module.exports = (crowi) => {
    *            description: id of userGroup
    *            schema:
    *              type: string
+   *          - name: searchWord
+   *            in: query
+   *            description: search word
+   *            schema:
+   *              type: string
+   *          - name: searchType
+   *            in: query
+   *            description: search type
+   *            schema:
+   *              type: string
+   *          - name: isAlsoNameSearched
+   *            in: query
+   *            description: whether name is also searched
+   *            schema:
+   *              type: boolean
+   *          - name: isAlsoMailSearched
+   *            in: query
+   *            description: whether mail is also searched
+   *            schema:
+   *              type: boolean
    *        responses:
    *          200:
    *            description: users are fetched
@@ -573,7 +717,7 @@ module.exports = (crowi) => {
    *                    users:
    *                      type: array
    *                      items:
-   *                        type: object
+   *                        $ref: '#/components/schemas/User'
    *                      description: user objects
    */
   router.get('/:id/unrelated-users', loginRequiredStrictly, adminRequired, async(req, res) => {
@@ -611,11 +755,13 @@ module.exports = (crowi) => {
    * @swagger
    *
    *  paths:
-   *    /user-groups/{id}/users:
+   *    /user-groups/{id}/users/{username}:
    *      post:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: addUserUserGroups
-   *        summary: /user-groups/{id}/users
+   *        summary: /user-groups/{id}/users/{username}
    *        description: Add a user to the userGroup
    *        parameters:
    *          - name: id
@@ -624,6 +770,12 @@ module.exports = (crowi) => {
    *            description: id of userGroup
    *            schema:
    *              type: string
+   *          - name: username
+   *            in: path
+   *            required: true
+   *            description: username of the user
+   *            schema:
+   *              type: string
    *        responses:
    *          200:
    *            description: a user is added
@@ -633,14 +785,11 @@ module.exports = (crowi) => {
    *                  type: object
    *                  properties:
    *                    user:
-   *                      type: object
+   *                      $ref: '#/components/schemas/User'
    *                      description: the user added to the group
-   *                    userGroup:
-   *                      type: object
-   *                      description: the group to which a user was added
-   *                    userGroupRelation:
-   *                      type: object
-   *                      description: the associative entity between user and userGroup
+   *                    createdRelationCount:
+   *                      type: number
+   *                      description: the number of relations created
    */
   router.post('/:id/users/:username', loginRequiredStrictly, adminRequired, validator.users.post, apiV3FormValidator, addActivity, async(req, res) => {
     const { id, username } = req.params;
@@ -678,11 +827,13 @@ module.exports = (crowi) => {
    * @swagger
    *
    *  paths:
-   *    /user-groups/{id}/users:
+   *    /user-groups/{id}/users/{username}:
    *      delete:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: deleteUsersUserGroups
-   *        summary: /user-groups/{id}/users
+   *        summary: /user-groups/{id}/users/{username}
    *        description: remove a user from the userGroup
    *        parameters:
    *          - name: id
@@ -691,6 +842,12 @@ module.exports = (crowi) => {
    *            description: id of userGroup
    *            schema:
    *              type: string
+   *          - name: username
+   *            in: path
+   *            required: true
+   *            description: username of the user
+   *            schema:
+   *              type: string
    *        responses:
    *          200:
    *            description: a user was removed
@@ -701,13 +858,11 @@ module.exports = (crowi) => {
    *                  properties:
    *                    user:
    *                      type: object
+   *                      $ref: '#/components/schemas/User'
    *                      description: the user removed from the group
-   *                    userGroup:
-   *                      type: object
-   *                      description: the group from which a user was removed
-   *                    userGroupRelation:
-   *                      type: object
-   *                      description: the associative entity between user and userGroup
+   *                    deletedGroupsCount:
+   *                      type: number
+   *                      description: the number of groups from which the user was removed
    */
   router.delete('/:id/users/:username', loginRequiredStrictly, adminRequired, validator.users.delete, apiV3FormValidator, async(req, res) => {
     const { id: userGroupId, username } = req.params;
@@ -733,6 +888,8 @@ module.exports = (crowi) => {
    *    /user-groups/{id}/user-group-relations:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getUserGroupRelationsUserGroups
    *        summary: /user-groups/{id}/user-group-relations
    *        description: Get the user group relations for the userGroup
@@ -780,6 +937,8 @@ module.exports = (crowi) => {
    *    /user-groups/{id}/pages:
    *      get:
    *        tags: [UserGroups]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: getPagesUserGroups
    *        summary: /user-groups/{id}/pages
    *        description: Get closed pages for the userGroup