update documentation to reflect modify-user changes

dreth · Aug 16, 2024 · 22eb9ec · 22eb9ec
1 parent 28617b0
commit 22eb9ec
Show file tree

Hide file tree

Showing 4 changed files with 17 additions and 14 deletions.
diff --git a/backend/auth/auth.go b/backend/auth/auth.go
@@ -286,14 +286,15 @@ func Me(c *gin.Context) {
 }
 
 // @Summary Modify a user's details
-// @Description This endpoint modifies a user's details such as Telegram bot API key, reminder time, and more. The request must include a valid JWT token.
+// @Description This endpoint modifies a user's details such as Telegram bot API key, reminder time, and more. The request must include a valid JWT token. When modifying the email or password, a new JWT token is generated and returned. Otherwise, the user's data is returned without a new token.
 // @Accept  json
 // @Produce  json
 // @Param   user  body     structs.ModifyUserRequest  true  "Modify user"
-// @Success 200 {object} structs.Success
+// @Success 200 {object} structs.LoginSuccess "User data and new token if email or password changed"
+// @Success 200 {object} structs.UserData "User data without a new token if no email or password changes"
 // @Failure 400 {object} structs.Error "Invalid request"
 // @Failure 401 {object} structs.Error "Unauthorized"
-// @Failure 500 {object} structs.Error "Failed to update user"
+// @Failure 500 {object} structs.Error "Failed to update user or process request"
 // @Security Bearer
 // @Router /modify-user [put]
 // @Tags auth

diff --git a/backend/docs/docs.go b/backend/docs/docs.go
@@ -408,7 +408,7 @@ const docTemplate = `{
                         "Bearer": []
                     }
                 ],
-                "description": "This endpoint modifies a user's details such as Telegram bot API key, reminder time, and more. The request must include a valid JWT token.",
+                "description": "This endpoint modifies a user's details such as Telegram bot API key, reminder time, and more. The request must include a valid JWT token. When modifying the email or password, a new JWT token is generated and returned. Otherwise, the user's data is returned without a new token.",
                 "consumes": [
                     "application/json"
                 ],
@@ -432,9 +432,9 @@ const docTemplate = `{
                 ],
                 "responses": {
                     "200": {
-                        "description": "OK",
+                        "description": "User data without a new token if no email or password changes",
                         "schema": {
-                            "$ref": "#/definitions/structs.Success"
+                            "$ref": "#/definitions/structs.UserData"
                         }
                     },
                     "400": {
@@ -450,7 +450,7 @@ const docTemplate = `{
                         }
                     },
                     "500": {
-                        "description": "Failed to update user",
+                        "description": "Failed to update user or process request",
                         "schema": {
                             "$ref": "#/definitions/structs.Error"
                         }

diff --git a/backend/docs/swagger.json b/backend/docs/swagger.json
@@ -397,7 +397,7 @@
                         "Bearer": []
                     }
                 ],
-                "description": "This endpoint modifies a user's details such as Telegram bot API key, reminder time, and more. The request must include a valid JWT token.",
+                "description": "This endpoint modifies a user's details such as Telegram bot API key, reminder time, and more. The request must include a valid JWT token. When modifying the email or password, a new JWT token is generated and returned. Otherwise, the user's data is returned without a new token.",
                 "consumes": [
                     "application/json"
                 ],
@@ -421,9 +421,9 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "OK",
+                        "description": "User data without a new token if no email or password changes",
                         "schema": {
-                            "$ref": "#/definitions/structs.Success"
+                            "$ref": "#/definitions/structs.UserData"
                         }
                     },
                     "400": {
@@ -439,7 +439,7 @@
                         }
                     },
                     "500": {
-                        "description": "Failed to update user",
+                        "description": "Failed to update user or process request",
                         "schema": {
                             "$ref": "#/definitions/structs.Error"
                         }

diff --git a/backend/docs/swagger.yaml b/backend/docs/swagger.yaml
@@ -435,6 +435,8 @@ paths:
       - application/json
       description: This endpoint modifies a user's details such as Telegram bot API
         key, reminder time, and more. The request must include a valid JWT token.
+        When modifying the email or password, a new JWT token is generated and returned.
+        Otherwise, the user's data is returned without a new token.
       parameters:
       - description: Modify user
         in: body
@@ -446,9 +448,9 @@ paths:
       - application/json
       responses:
         "200":
-          description: OK
+          description: User data without a new token if no email or password changes
           schema:
-            $ref: '#/definitions/structs.Success'
+            $ref: '#/definitions/structs.UserData'
         "400":
           description: Invalid request
           schema:
@@ -458,7 +460,7 @@ paths:
           schema:
             $ref: '#/definitions/structs.Error'
         "500":
-          description: Failed to update user
+          description: Failed to update user or process request
           schema:
             $ref: '#/definitions/structs.Error'
       security: