Merge pull request #149 from crupest/swagger

Swagger/OpenAPI

1 files changed, 45 insertions, 19 deletions

diff --git a/Timeline/Controllers/UserAvatarController.cs b/Timeline/Controllers/UserAvatarController.cs
index b2e2e852..32f63fc6 100644
--- a/Timeline/Controllers/UserAvatarController.cs
+++ b/Timeline/Controllers/UserAvatarController.cs
@@ -3,10 +3,12 @@ using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;

 using Microsoft.Extensions.Logging;

 using System;

+using System.IO;

 using System.Threading.Tasks;

 using Timeline.Auth;

 using Timeline.Filters;

 using Timeline.Helpers;

+using Timeline.Models;

 using Timeline.Models.Http;

 using Timeline.Models.Validation;

 using Timeline.Services;

@@ -15,7 +17,11 @@ using static Timeline.Resources.Controllers.UserAvatarController;
 

 namespace Timeline.Controllers

 {

+    /// <summary>

+    /// Operations about user avatar.

+    /// </summary>

     [ApiController]

+    [ProducesErrorResponseType(typeof(CommonResponse))]

     public class UserAvatarController : Controller

     {

         private readonly ILogger<UserAvatarController> _logger;

@@ -23,6 +29,9 @@ namespace Timeline.Controllers
         private readonly IUserService _userService;

         private readonly IUserAvatarService _service;

 

+        /// <summary>

+        /// 

+        /// </summary>

         public UserAvatarController(ILogger<UserAvatarController> logger, IUserService userService, IUserAvatarService service)

         {

             _logger = logger;

@@ -30,9 +39,19 @@ namespace Timeline.Controllers
             _service = service;

         }

 

+        /// <summary>

+        /// Get avatar of a user.

+        /// </summary>

+        /// <param name="username">Username of the user to get avatar of.</param>

+        /// <param name="ifNoneMatch">If-None-Match header.</param>

+        /// <returns>Avatar data.</returns>

         [HttpGet("users/{username}/avatar")]

-        public async Task<IActionResult> Get([FromRoute][Username] string username)

+        [ProducesResponseType(typeof(byte[]), StatusCodes.Status200OK)]

+        [ProducesResponseType(typeof(void), StatusCodes.Status304NotModified)]

+        [ProducesResponseType(StatusCodes.Status404NotFound)]

+        public async Task<IActionResult> Get([FromRoute][Username] string username, [FromHeader(Name = "If-None-Match")] string? ifNoneMatch)

         {

+            _ = ifNoneMatch;

             long id;

             try

             {

@@ -51,16 +70,21 @@ namespace Timeline.Controllers
             });

         }

 

+        /// <summary>

+        /// Set avatar of a user. You have to be administrator to change other's.

+        /// </summary>

+        /// <param name="username">Username of the user to set avatar of.</param>

+        /// <param name="body">The avatar data.</param>

         [HttpPut("users/{username}/avatar")]

         [Authorize]

-        [RequireContentType, RequireContentLength]

         [Consumes("image/png", "image/jpeg", "image/gif", "image/webp")]

-        public async Task<IActionResult> Put([FromRoute][Username] string username)

+        [MaxContentLength(1000 * 1000 * 10)]

+        [ProducesResponseType(typeof(void), StatusCodes.Status200OK)]

+        [ProducesResponseType(StatusCodes.Status400BadRequest)]

+        [ProducesResponseType(StatusCodes.Status401Unauthorized)]

+        [ProducesResponseType(StatusCodes.Status403Forbidden)]

+        public async Task<IActionResult> Put([FromRoute][Username] string username, [FromBody] ByteData body)

         {

-            var contentLength = Request.ContentLength!.Value;

-            if (contentLength > 1000 * 1000 * 10)

-                return BadRequest(ErrorResponse.Common.Content.TooBig("10MB"));

-

             if (!User.IsAdministrator() && User.Identity.Name != username)

             {

                 _logger.LogInformation(Log.Format(LogPutForbid,

@@ -81,20 +105,10 @@ namespace Timeline.Controllers
 

             try

             {

-                var data = new byte[contentLength];

-                var bytesRead = await Request.Body.ReadAsync(data);

-

-                if (bytesRead != contentLength)

-                    return BadRequest(ErrorResponse.Common.Content.UnmatchedLength_Smaller());

-

-                var extraByte = new byte[1];

-                if (await Request.Body.ReadAsync(extraByte) != 0)

-                    return BadRequest(ErrorResponse.Common.Content.UnmatchedLength_Bigger());

-

                 await _service.SetAvatar(id, new Avatar

                 {

-                    Data = data,

-                    Type = Request.ContentType

+                    Data = body.Data,

+                    Type = body.ContentType

                 });

 

                 _logger.LogInformation(Log.Format(LogPutSuccess,

@@ -115,7 +129,19 @@ namespace Timeline.Controllers
             }

         }

 

+        /// <summary>

+        /// Reset the avatar to the default one. You have to be administrator to reset other's.

+        /// </summary>

+        /// <param name="username">Username of the user.</param>

+        /// <response code="200">Succeeded to reset.</response>

+        /// <response code="400">Error code is 10010001 if 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}/avatar")]

+        [ProducesResponseType(typeof(void), StatusCodes.Status200OK)]

+        [ProducesResponseType(StatusCodes.Status400BadRequest)]

+        [ProducesResponseType(StatusCodes.Status401Unauthorized)]

+        [ProducesResponseType(StatusCodes.Status403Forbidden)]

         [Authorize]

         public async Task<IActionResult> Delete([FromRoute][Username] string username)

         {