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/TokenController.cs | 20 +++++++++++
 Timeline/Controllers/UserController.cs  | 59 +++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)

(limited to 'Timeline/Controllers')

diff --git a/Timeline/Controllers/TokenController.cs b/Timeline/Controllers/TokenController.cs
index cd67225c..7792b318 100644
--- a/Timeline/Controllers/TokenController.cs
+++ b/Timeline/Controllers/TokenController.cs
@@ -1,5 +1,6 @@
 using AutoMapper;
 using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
 using System;
@@ -13,8 +14,12 @@ using static Timeline.Resources.Controllers.TokenController;
 
 namespace Timeline.Controllers
 {
+    /// <summary>
+    /// Operation about tokens.
+    /// </summary>
     [Route("token")]
     [ApiController]
+    [ProducesErrorResponseType(typeof(CommonResponse))]
     public class TokenController : Controller
     {
         private readonly IUserTokenManager _userTokenManager;
@@ -23,6 +28,7 @@ namespace Timeline.Controllers
 
         private readonly IMapper _mapper;
 
+        /// <summary></summary>
         public TokenController(IUserTokenManager userTokenManager, ILogger<TokenController> logger, IClock clock, IMapper mapper)
         {
             _userTokenManager = userTokenManager;
@@ -31,8 +37,15 @@ namespace Timeline.Controllers
             _mapper = mapper;
         }
 
+        /// <summary>
+        /// Create a new token for a user.
+        /// </summary>
+        /// <response code="200">Succeed to create token.</response>
+        /// <response code="400">Error code is 11010101 if user does not exist or password is wrong.</response>
         [HttpPost("create")]
         [AllowAnonymous]
+        [ProducesResponseType(typeof(CreateTokenResponse), StatusCodes.Status200OK)]
+        [ProducesResponseType(StatusCodes.Status400BadRequest)]
         public async Task<ActionResult<CreateTokenResponse>> Create([FromBody] CreateTokenRequest request)
         {
             void LogFailure(string reason, Exception? e = null)
@@ -75,8 +88,15 @@ namespace Timeline.Controllers
             }
         }
 
+        /// <summary>
+        /// Verify a token.
+        /// </summary>
+        /// <response code="200">Token is valid.</response>
+        /// <response code="400">Error code is 11010201 if token is of bad format (it may not be created by this server). Error code is 11010202 if user does not exist. Error code is 11010203 if token is of old version (user may have changed password). Error code is 11010204 if token is expired.</response>
         [HttpPost("verify")]
         [AllowAnonymous]
+        [ProducesResponseType(typeof(VerifyTokenResponse), StatusCodes.Status200OK)]
+        [ProducesResponseType(StatusCodes.Status400BadRequest)]
         public async Task<ActionResult<VerifyTokenResponse>> Verify([FromBody] VerifyTokenRequest request)
         {
             void LogFailure(string reason, Exception? e = null, params (string, object?)[] otherProperties)
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