From 81f6ecd9685c5a6bae0da5050b5edfaf050167cc Mon Sep 17 00:00:00 2001 From: crupest Date: Fri, 21 Aug 2020 17:41:29 +0800 Subject: ... --- Timeline/Controllers/TimelineController.cs | 144 ++++++++++++++++++++++++++++- 1 file changed, 143 insertions(+), 1 deletion(-) (limited to 'Timeline/Controllers/TimelineController.cs') diff --git a/Timeline/Controllers/TimelineController.cs b/Timeline/Controllers/TimelineController.cs index 72404ea3..b376bce5 100644 --- a/Timeline/Controllers/TimelineController.cs +++ b/Timeline/Controllers/TimelineController.cs @@ -17,8 +17,12 @@ using Timeline.Services.Exceptions; namespace Timeline.Controllers { + /// + /// Operations about timeline. + /// [ApiController] [CatchTimelineNotExistException] + [ProducesErrorResponseType(typeof(CommonResponse))] public class TimelineController : Controller { private readonly ILogger _logger; @@ -28,6 +32,9 @@ namespace Timeline.Controllers private readonly IMapper _mapper; + /// + /// + /// public TimelineController(ILogger logger, IUserService userService, ITimelineService service, IMapper mapper) { _logger = logger; @@ -36,7 +43,17 @@ namespace Timeline.Controllers _mapper = mapper; } + /// + /// List all timelines. + /// + /// A username. If set, only timelines related to the user will return. + /// Specify the relation type, may be 'own' or 'join'. If not set, both type will return. + /// "Private" or "Register" or "Public". If set, only timelines whose visibility is specified one will return. + /// Succeeded to get timelines. + /// Model is invalid. Or user specified by "relate" param does not exist. [HttpGet("timelines")] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status400BadRequest)] public async Task>> TimelineList([FromQuery][Username] string? relate, [FromQuery][RegularExpression("(own)|(join)")] string? relateType, [FromQuery] string? visibility) { List? visibilityFilter = null; @@ -93,7 +110,20 @@ namespace Timeline.Controllers return result; } + /// + /// Get info of a timeline. + /// + /// The timeline name. + /// A unique id. If specified and if-modified-since is also specified, the timeline info will return when unique id is not the specified one even if it is not modified. + /// Same effect as If-Modified-Since header and take precedence than it. + /// If specified, will return 304 if not modified. + /// Succeeded to get timeline info. + /// Timeline not change. + /// Timeline does not exist. [HttpGet("timelines/{name}")] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status304NotModified)] + [ProducesResponseType(StatusCodes.Status404NotFound)] public async Task> TimelineGet([FromRoute][GeneralTimelineName] string name, [FromQuery] string? checkUniqueId, [FromQuery(Name = "ifModifiedSince")] DateTime? queryIfModifiedSince, [FromHeader(Name = "If-Modified-Since")] DateTime? headerIfModifiedSince) { DateTime? ifModifiedSince = null; @@ -140,7 +170,19 @@ namespace Timeline.Controllers } } + /// + /// Get posts of a timeline. You need to have permission. + /// + /// The name of the timeline. + /// If set, only posts modified since the time will return. + /// If set to true, deleted post will also return. + /// Succeeded to get posts. + /// You have no permission. + /// The timeline does not exist. [HttpGet("timelines/{name}/posts")] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status403Forbidden)] + [ProducesResponseType(StatusCodes.Status404NotFound)] public async Task>> PostListGet([FromRoute][GeneralTimelineName] string name, [FromQuery] DateTime? modifiedSince, [FromQuery] bool? includeDeleted) { if (!this.IsAdministrator() && !await _service.HasReadPermission(name, this.GetOptionalUserId())) @@ -154,9 +196,26 @@ namespace Timeline.Controllers return result; } + /// + /// Get the data of a post. Usually a image post. You need to have permission. + /// + /// Timeline name. + /// The id of the post. + /// If-None-Match header. + /// Succeeded to get data. + /// Data not changed. + /// Error code is 11040502 if post has no data. + /// You have no permission. + /// Timeline or post does not exist. [HttpGet("timelines/{name}/posts/{id}/data")] - public async Task>> PostDataGet([FromRoute][GeneralTimelineName] string name, [FromRoute] long id) + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(typeof(void), StatusCodes.Status304NotModified)] + [ProducesResponseType(StatusCodes.Status400BadRequest)] + [ProducesResponseType(StatusCodes.Status403Forbidden)] + [ProducesResponseType(StatusCodes.Status404NotFound)] + public async Task PostDataGet([FromRoute][GeneralTimelineName] string name, [FromRoute] long id, [FromHeader(Name = "If-None-Match")] string? ifNoneMatch) { + _ = ifNoneMatch; if (!this.IsAdministrator() && !await _service.HasReadPermission(name, this.GetOptionalUserId())) { return StatusCode(StatusCodes.Status403Forbidden, ErrorResponse.Common.Forbid()); @@ -180,8 +239,22 @@ namespace Timeline.Controllers } } + /// + /// Create a new post. You need to have permission. + /// + /// Timeline name. + /// + /// Info of new post. + /// Succeeded to create post and return info of new post. + /// Body model is invalid. + /// You have not logged in. + /// You have no permission. [HttpPost("timelines/{name}/posts")] [Authorize] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status400BadRequest)] + [ProducesResponseType(StatusCodes.Status401Unauthorized)] + [ProducesResponseType(StatusCodes.Status403Forbidden)] public async Task> PostPost([FromRoute][GeneralTimelineName] string name, [FromBody] TimelinePostCreateRequest body) { var id = this.GetUserId(); @@ -238,8 +311,19 @@ namespace Timeline.Controllers return result; } + /// + /// Delete a post. + /// + /// Timeline name. + /// Post id. + /// Succeeded to delete post. Or post does not exist. + /// You have not logged in. + /// You have no permission. [HttpDelete("timelines/{name}/posts/{id}")] [Authorize] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status401Unauthorized)] + [ProducesResponseType(StatusCodes.Status403Forbidden)] public async Task> PostDelete([FromRoute][GeneralTimelineName] string name, [FromRoute] long id) { if (!this.IsAdministrator() && !await _service.HasPostModifyPermission(name, id, this.GetUserId())) @@ -257,8 +341,20 @@ namespace Timeline.Controllers } } + /// + /// Change properties of a timeline. + /// + /// Timeline name. + /// + /// The new info. + /// Succeeded to change properties of timeline. Return the new info. + /// You have not logged in. + /// You have no permission. [HttpPatch("timelines/{name}")] [Authorize] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status401Unauthorized)] + [ProducesResponseType(StatusCodes.Status403Forbidden)] public async Task> TimelinePatch([FromRoute][GeneralTimelineName] string name, [FromBody] TimelinePatchRequest body) { if (!this.IsAdministrator() && !(await _service.HasManagePermission(name, this.GetUserId()))) @@ -271,8 +367,21 @@ namespace Timeline.Controllers return result; } + /// + /// Add a member to timeline. + /// + /// Timeline name. + /// The new member's username. + /// Succeeded. + /// User does not exist. + /// You have not logged in. + /// You have no permission. [HttpPut("timelines/{name}/members/{member}")] [Authorize] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status400BadRequest)] + [ProducesResponseType(StatusCodes.Status401Unauthorized)] + [ProducesResponseType(StatusCodes.Status403Forbidden)] public async Task TimelineMemberPut([FromRoute][GeneralTimelineName] string name, [FromRoute][Username] string member) { if (!this.IsAdministrator() && !(await _service.HasManagePermission(name, this.GetUserId()))) @@ -291,8 +400,19 @@ namespace Timeline.Controllers } } + /// + /// Remove a member from timeline. + /// + /// Timeline name. + /// The member's username. + /// Succeeded. Or the user is not a member. + /// You have not logged in. + /// You have no permission. [HttpDelete("timelines/{name}/members/{member}")] [Authorize] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status401Unauthorized)] + [ProducesResponseType(StatusCodes.Status403Forbidden)] public async Task TimelineMemberDelete([FromRoute][GeneralTimelineName] string name, [FromRoute][Username] string member) { if (!this.IsAdministrator() && !(await _service.HasManagePermission(name, this.GetUserId()))) @@ -311,8 +431,19 @@ namespace Timeline.Controllers } } + /// + /// Create a timeline. + /// + /// + /// Info of new timeline. + /// Succeeded and return info of new timeline. + /// Timeline name is conflict. + /// You have not logged in. [HttpPost("timelines")] [Authorize] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status400BadRequest)] + [ProducesResponseType(StatusCodes.Status401Unauthorized)] public async Task> TimelineCreate([FromBody] TimelineCreateRequest body) { var userId = this.GetUserId(); @@ -329,8 +460,19 @@ namespace Timeline.Controllers } } + /// + /// Delete a timeline. + /// + /// Timeline name. + /// Succeeded. Or timeline does not exist. + /// You have not logged in. + /// You have no permission. [HttpDelete("timelines/{name}")] [Authorize] + [ProducesResponseType(StatusCodes.Status200OK)] + [ProducesResponseType(StatusCodes.Status400BadRequest)] + [ProducesResponseType(StatusCodes.Status401Unauthorized)] + [ProducesResponseType(StatusCodes.Status403Forbidden)] public async Task> TimelineDelete([FromRoute][TimelineName] string name) { if (!this.IsAdministrator() && !(await _service.HasManagePermission(name, this.GetUserId()))) -- cgit v1.2.3