From 32fdf425e6b4f4edfb727fb3c0cbebe2c87fd663 Mon Sep 17 00:00:00 2001
From: crupest <crupest@outlook.com>
Date: Thu, 20 Aug 2020 00:39:09 +0800
Subject: ...

---
 Timeline/Controllers/UserController.cs | 59 ++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

(limited to 'Timeline/Controllers/UserController.cs')

diff --git a/Timeline/Controllers/UserController.cs b/Timeline/Controllers/UserController.cs
index 3986bb5b..fa2d37d8 100644
--- a/Timeline/Controllers/UserController.cs
+++ b/Timeline/Controllers/UserController.cs
@@ -17,7 +17,11 @@ using static Timeline.Resources.Messages;
 
 namespace Timeline.Controllers
 {
+    /// <summary>
+    /// Operations about users.
+    /// </summary>
     [ApiController]
+    [ProducesErrorResponseType(typeof(CommonResponse))]
     public class UserController : Controller
     {
         private readonly ILogger<UserController> _logger;
@@ -25,6 +29,7 @@ namespace Timeline.Controllers
         private readonly IUserDeleteService _userDeleteService;
         private readonly IMapper _mapper;
 
+        /// <summary></summary>
         public UserController(ILogger<UserController> logger, IUserService userService, IUserDeleteService userDeleteService, IMapper mapper)
         {
             _logger = logger;
@@ -35,7 +40,12 @@ namespace Timeline.Controllers
 
         private UserInfo ConvertToUserInfo(User user) => _mapper.Map<UserInfo>(user);
 
+        /// <summary>
+        /// Get all users.
+        /// </summary>
+        /// <response code="200">The user list.</response>
         [HttpGet("users")]
+        [ProducesResponseType(typeof(UserInfo[]), StatusCodes.Status200OK)]
         public async Task<ActionResult<UserInfo[]>> List()
         {
             var users = await _userService.GetUsers();
@@ -43,7 +53,13 @@ namespace Timeline.Controllers
             return Ok(result);
         }
 
+        /// <summary>
+        /// Get a user info.
+        /// </summary>
+        /// <param name="username">Username of the user.</param>
+        /// <response code="200">The user info.</response>
         [HttpGet("users/{username}")]
+        [ProducesResponseType(typeof(UserInfo), StatusCodes.Status200OK)]
         public async Task<ActionResult<UserInfo>> Get([FromRoute][Username] string username)
         {
             try
@@ -58,7 +74,20 @@ namespace Timeline.Controllers
             }
         }
 
+        /// <summary>
+        /// Change a user's property. You have to be administrator in some condition.
+        /// </summary>
+        /// <param name="body"></param>
+        /// <param name="username">Username of the user to change.</param>
+        /// <response code="200">Succeed to change the user and return the new user info.</response>
+        /// <response code="401">You have not logged in.</response>
+        /// <response code="403">You are not administrator.</response>
+        /// <response code="404">The user to change does not exist.</response>
         [HttpPatch("users/{username}"), Authorize]
+        [ProducesResponseType(typeof(UserInfo), StatusCodes.Status200OK)]
+        [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+        [ProducesResponseType(StatusCodes.Status403Forbidden)]
+        [ProducesResponseType(StatusCodes.Status404NotFound)]
         public async Task<ActionResult<UserInfo>> Patch([FromBody] UserPatchRequest body, [FromRoute][Username] string username)
         {
             if (this.IsAdministrator())
@@ -101,7 +130,17 @@ namespace Timeline.Controllers
             }
         }
 
+        /// <summary>
+        /// Delete a user and all his related data. You have to be administrator.
+        /// </summary>
+        /// <param name="username">Username of the user to delete.</param>
+        /// <response code="200">Succeeded to delete or the user does not exist.</response>
+        /// <response code="401">You have not logged in.</response>
+        /// <response code="403">You are not administrator.</response>
         [HttpDelete("users/{username}"), AdminAuthorize]
+        [ProducesResponseType(typeof(CommonDeleteResponse), StatusCodes.Status200OK)]
+        [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+        [ProducesResponseType(StatusCodes.Status403Forbidden)]
         public async Task<ActionResult<CommonDeleteResponse>> Delete([FromRoute][Username] string username)
         {
             var delete = await _userDeleteService.DeleteUser(username);
@@ -111,7 +150,18 @@ namespace Timeline.Controllers
                 return Ok(CommonDeleteResponse.NotExist());
         }
 
+        /// <summary>
+        /// Create a new user. You have to be administrator.
+        /// </summary>
+        /// <response code="200">Succeeded to create a new user and return his user info.</response>
+        /// <response code="400">Error code is 11020101 if a user with given username already exists.</response>
+        /// <response code="401">You have not logged in.</response>
+        /// <response code="403">You are not administrator.</response>
         [HttpPost("userop/createuser"), AdminAuthorize]
+        [ProducesResponseType(typeof(UserInfo), StatusCodes.Status200OK)]
+        [ProducesResponseType(StatusCodes.Status400BadRequest)]
+        [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+        [ProducesResponseType(StatusCodes.Status403Forbidden)]
         public async Task<ActionResult<UserInfo>> CreateUser([FromBody] CreateUserRequest body)
         {
             try
@@ -125,7 +175,16 @@ namespace Timeline.Controllers
             }
         }
 
+        /// <summary>
+        /// Change password with old password.
+        /// </summary>
+        /// <response code="200">Succeeded to change password.</response>
+        /// <response code="400">Error code is 11020201 if old password is wrong.</response>
+        /// <response code="401">You have not logged in.</response>
         [HttpPost("userop/changepassword"), Authorize]
+        [ProducesResponseType(typeof(void), StatusCodes.Status200OK)]
+        [ProducesResponseType(StatusCodes.Status400BadRequest)]
+        [ProducesResponseType(StatusCodes.Status401Unauthorized)]
         public async Task<ActionResult> ChangePassword([FromBody] ChangePasswordRequest request)
         {
             try
-- 
cgit v1.2.3