Merge pull request #9739 from goofmint/fix/doc-v3-users

support(jsdoc): add swagger document to users.js

apps/app/src/server/routes/apiv3/users.js

@@ -235,6 +235,11 @@ module.exports = (crowi) => {
    *            description: sorting column
    *            schema:
    *              type: string
+   *          - name: forceIncludeAttributes
+   *            in: query
+   *            description: force include attributes
+   *            schema:
+   *              type: string
    *        responses:
    *          200:
    *            description: users are fetched
@@ -406,6 +411,8 @@ module.exports = (crowi) => {
    *    /users/invite:
    *      post:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: inviteUser
    *        summary: /users/invite
    *        description: Create new users and send Emails
@@ -428,14 +435,23 @@ module.exports = (crowi) => {
    *                schema:
    *                  properties:
    *                    createdUserList:
-   *                      type: object
+   *                      $ref: '#/components/schemas/User'
    *                      description: Users successfully created
    *                    existingEmailList:
-   *                      type: object
+   *                      type: array
    *                      description: Users email that already exists
+   *                      items:
+   *                        type: string
    *                    failedEmailList:
    *                      type: object
    *                      description: Users email that failed to create or send email
+   *                      properties:
+   *                        email:
+   *                          type: string
+   *                          description: email address
+   *                        reason:
+   *                          type: string
+   *                          description: reason for failure
    */
   router.post('/invite', loginRequiredStrictly, adminRequired, addActivity, validator.inviteEmail, apiV3FormValidator, async(req, res) => {
 
@@ -474,6 +490,8 @@ module.exports = (crowi) => {
    *    /users/{id}/grant-admin:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: grantAdminUser
    *        summary: /users/{id}/grant-admin
    *        description: Grant user admin
@@ -492,7 +510,7 @@ module.exports = (crowi) => {
    *                schema:
    *                  properties:
    *                    userData:
-   *                      type: object
+   *                      $ref: '#/components/schemas/User'
    *                      description: data of admin user
    */
   router.put('/:id/grant-admin', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => {
@@ -521,6 +539,8 @@ module.exports = (crowi) => {
    *    /users/{id}/revoke-admin:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: revokeAdminUser
    *        summary: /users/{id}/revoke-admin
    *        description: Revoke user admin
@@ -568,6 +588,8 @@ module.exports = (crowi) => {
    *    /users/{id}/grant-read-only:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: ReadOnly
    *        summary: /users/{id}/grant-read-only
    *        description: Grant user read only access
@@ -586,8 +608,8 @@ module.exports = (crowi) => {
    *                schema:
    *                  properties:
    *                    userData:
-   *                      type: object
-   *                      description: data of read only
+   *                      $ref: '#/components/schemas/User'
+   *                      description: data of grant read only
    */
   router.put('/:id/grant-read-only', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => {
     const { id } = req.params;
@@ -620,6 +642,8 @@ module.exports = (crowi) => {
    *    /users/{id}/revoke-read-only:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: revokeReadOnly
    *        summary: /users/{id}/revoke-read-only
    *        description: Revoke user read only access
@@ -638,7 +662,7 @@ module.exports = (crowi) => {
    *                schema:
    *                  properties:
    *                    userData:
-   *                      type: object
+   *                      $ref: '#/components/schemas/User'
    *                      description: data of revoke read only
    */
   router.put('/:id/revoke-read-only', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => {
@@ -672,6 +696,8 @@ module.exports = (crowi) => {
    *    /users/{id}/activate:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: activateUser
    *        summary: /users/{id}/activate
    *        description: Activate user
@@ -690,7 +716,7 @@ module.exports = (crowi) => {
    *                schema:
    *                  properties:
    *                    userData:
-   *                      type: object
+   *                      $ref: '#/components/schemas/User'
    *                      description: data of activate user
    */
   router.put('/:id/activate', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => {
@@ -726,6 +752,8 @@ module.exports = (crowi) => {
    *    /users/{id}/deactivate:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: deactivateUser
    *        summary: /users/{id}/deactivate
    *        description: Deactivate user
@@ -744,7 +772,7 @@ module.exports = (crowi) => {
    *                schema:
    *                  properties:
    *                    userData:
-   *                      type: object
+   *                      $ref: '#/components/schemas/User'
    *                      description: data of deactivate user
    */
   router.put('/:id/deactivate', loginRequiredStrictly, adminRequired, certifyUserOperationOtherThenYourOwn, addActivity, async(req, res) => {
@@ -773,6 +801,8 @@ module.exports = (crowi) => {
    *    /users/{id}/remove:
    *      delete:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: removeUser
    *        summary: /users/{id}/remove
    *        description: Delete user
@@ -791,7 +821,7 @@ module.exports = (crowi) => {
    *                schema:
    *                  properties:
    *                    user:
-   *                      type: object
+   *                      $ref: '#/components/schemas/User'
    *                      description: data of deleted user
    */
   router.delete('/:id/remove', loginRequiredStrictly, adminRequired, certifyUserOperationOtherThenYourOwn, addActivity, async(req, res) => {
@@ -835,9 +865,17 @@ module.exports = (crowi) => {
    *    /users/external-accounts:
    *      get:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: listExternalAccountsUsers
    *        summary: /users/external-accounts
    *        description: Get external-account
+   *        parameters:
+   *          - name: page
+   *            in: query
+   *            description: page number
+   *            schema:
+   *              type: number
    *        responses:
    *          200:
    *            description: external-account are fetched
@@ -868,6 +906,8 @@ module.exports = (crowi) => {
    *    /users/external-accounts/{id}/remove:
    *      delete:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: removeExternalAccountUser
    *        summary: /users/external-accounts/{id}/remove
    *        description: Delete ExternalAccount
@@ -911,25 +951,29 @@ module.exports = (crowi) => {
    *    /users/update.imageUrlCache:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: update.imageUrlCache
    *        summary: /users/update.imageUrlCache
    *        description: update imageUrlCache
-   *        parameters:
-   *          - name:  userIds
-   *            in: query
-   *            description: user id list
+   *        requestBody:
+   *          content:
+   *           application/json:
    *            schema:
-   *              type: string
+   *             properties:
+   *              userIds:
+   *                type: array
+   *                description: user id list
+   *                items:
+   *                  type: string
    *        responses:
    *          200:
    *            description: success creating imageUrlCached
    *            content:
    *              application/json:
    *                schema:
-   *                  properties:
-   *                    userData:
-   *                      type: object
-   *                      description: users updated with imageUrlCached
+   *                  type: object
+   *                  description: success creating imageUrlCached
    */
   router.put('/update.imageUrlCache', loginRequiredStrictly, adminRequired, async(req, res) => {
     try {
@@ -963,6 +1007,8 @@ module.exports = (crowi) => {
    *    /users/reset-password:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: resetPassword
    *        summary: /users/reset-password
    *        description: update imageUrlCache
@@ -971,14 +1017,21 @@ module.exports = (crowi) => {
    *            application/json:
    *              schema:
    *                properties:
-   *                  newPassword:
-   *                    type: string
-   *                  user:
+   *                  id:
    *                    type: string
    *                    description: user id for reset password
    *        responses:
    *          200:
    *            description: success reset password
+   *            content:
+   *              application/json:
+   *                schema:
+   *                 properties:
+   *                  newPassword:
+   *                    type: string
+   *                    description: new password
+   *                  user:
+   *                    $ref: '#/components/schemas/User'
    */
   router.put('/reset-password', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => {
     const { id } = req.body;
@@ -1004,6 +1057,8 @@ module.exports = (crowi) => {
    *    /users/reset-password-email:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: resetPasswordEmail
    *        summary: /users/reset-password-email
    *        description: send new password email
@@ -1012,11 +1067,11 @@ module.exports = (crowi) => {
    *            application/json:
    *              schema:
    *                properties:
-   *                  newPassword:
-   *                    type: string
-   *                  user:
+   *                  id:
    *                    type: string
    *                    description: user id for send new password email
+   *                  newPassword:
+   *                    type: string
    *        responses:
    *          200:
    *            description: success send new password email
@@ -1051,6 +1106,8 @@ module.exports = (crowi) => {
    *    /users/send-invitation-email:
    *      put:
    *        tags: [Users Management]
+   *        security:
+   *          - cookieAuth: []
    *        operationId: sendInvitationEmail
    *        summary: /users/send-invitation-email
    *        description: send invitation email
@@ -1072,6 +1129,11 @@ module.exports = (crowi) => {
    *                    failedToSendEmail:
    *                      type: object
    *                      description: email and reasons for email sending failure
+   *                      properties:
+   *                        email:
+   *                          type: string
+   *                        reason:
+   *                          type: string
    */
   router.put('/send-invitation-email', loginRequiredStrictly, adminRequired, addActivity, async(req, res) => {
     const { id } = req.body;
@@ -1160,6 +1222,81 @@ module.exports = (crowi) => {
     return res.apiv3(data);
   });
 
+  /**
+    * @swagger
+    *
+    *    paths:
+    *      /users/usernames:
+    *        get:
+    *          tags: [Users]
+    *          summary: /users/usernames
+    *          operationId: getUsernames
+    *          description: Get list of usernames
+    *          parameters:
+    *            - in: query
+    *              name: q
+    *              schema:
+    *                type: string
+    *                description: query string to search usernames
+    *                example: alice
+    *            - in: query
+    *              name: offset
+    *              schema:
+    *                type: integer
+    *                description: offset for pagination
+    *                example: 0
+    *            - in: query
+    *              name: limit
+    *              schema:
+    *                type: integer
+    *                description: limit for pagination
+    *                example: 10
+    *            - in: query
+    *              name: options
+    *              schema:
+    *                type: string
+    *                description: options for including different types of users
+    *                example: '{"isIncludeActiveUser": true, "isIncludeInactiveUser": true,
+    *                          "isIncludeActivitySnapshotUser": true, "isIncludeMixedUsernames": true}'
+    *          responses:
+    *            200:
+    *              description: Succeeded to get list of usernames.
+    *              content:
+    *                application/json:
+    *                  schema:
+    *                    properties:
+    *                      activeUser:
+    *                        type: object
+    *                        properties:
+    *                          usernames:
+    *                            type: array
+    *                            items:
+    *                              type: string
+    *                          totalCount:
+    *                            type: integer
+    *                      inactiveUser:
+    *                        type: object
+    *                        properties:
+    *                          usernames:
+    *                            type: array
+    *                            items:
+    *                              type: string
+    *                          totalCount:
+    *                            type: integer
+    *                      activitySnapshotUser:
+    *                        type: object
+    *                        properties:
+    *                          usernames:
+    *                            type: array
+    *                            items:
+    *                              type: string
+    *                          totalCount:
+    *                            type: integer
+    *                      mixedUsernames:
+    *                        type: array
+    *                        items:
+    *                          type: string
+    */
   router.get('/usernames', accessTokenParser, loginRequired, validator.usernames, apiV3FormValidator, async(req, res) => {
     const q = req.query.q;
     const offset = +req.query.offset || 0;