docs: specify response types of all endpoints

crowdparlay · Feb 10, 2024 · 408ee57 · 408ee57
1 parent 2dcea40
commit 408ee57
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 2 deletions.
diff --git a/src/CrowdParlay.Social.Api/v1/Controllers/AuthorsController.cs b/src/CrowdParlay.Social.Api/v1/Controllers/AuthorsController.cs
@@ -1,3 +1,4 @@
+using System.Net;
 using CrowdParlay.Social.Application.Abstractions;
 using CrowdParlay.Social.Application.DTOs;
 using Microsoft.AspNetCore.Mvc;
@@ -15,6 +16,9 @@ public class AuthorsController : ControllerBase
     /// Returns author with the specified ID.
     /// </summary>
     [HttpGet("{authorId}")]
+    [ProducesResponseType(typeof(AuthorDto), (int)HttpStatusCode.OK)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.InternalServerError)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.NotFound)]
     public async Task<AuthorDto> GetAuthorById([FromRoute] Guid authorId) =>
         await _authors.GetByIdAsync(authorId);
 }
diff --git a/src/CrowdParlay.Social.Api/v1/Controllers/CommentsController.cs b/src/CrowdParlay.Social.Api/v1/Controllers/CommentsController.cs
@@ -1,3 +1,4 @@
+using System.Net;
 using CrowdParlay.Social.Api.Extensions;
 using CrowdParlay.Social.Api.v1.DTOs;
 using CrowdParlay.Social.Application.Abstractions;
@@ -19,13 +20,19 @@ public class CommentsController : ControllerBase
     /// Returns comment with the specified ID.
     /// </summary>
     [HttpGet("{commentId}")]
+    [ProducesResponseType(typeof(CommentDto), (int)HttpStatusCode.OK)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.InternalServerError)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.NotFound)]
     public async Task<CommentDto> GetCommentById([FromRoute] Guid commentId) =>
         await _comments.GetByIdAsync(commentId);
 
     /// <summary>
     /// Get comments by filters.
     /// </summary>
     [HttpGet]
+    [ProducesResponseType(typeof(IEnumerable<CommentDto>), (int)HttpStatusCode.OK)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.InternalServerError)]
+    [ProducesResponseType(typeof(ValidationProblem), (int)HttpStatusCode.BadRequest)]
     public async Task<IEnumerable<CommentDto>> SearchComments(
         [FromQuery] Guid? discussionId,
         [FromQuery] Guid? authorId,
@@ -37,20 +44,28 @@ public async Task<IEnumerable<CommentDto>> SearchComments(
     /// Creates a top-level comment in discussion.
     /// </summary>
     [HttpPost]
+    [ProducesResponseType(typeof(CommentDto), (int)HttpStatusCode.Created)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.InternalServerError)]
+    [ProducesResponseType(typeof(ValidationProblem), (int)HttpStatusCode.BadRequest)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.Forbidden)]
     public async Task<ActionResult<CommentDto>> Create([FromBody] CommentRequest request)
     {
         var authorId =
             User.GetUserId()
             ?? throw new ForbiddenException();
 
         var response = await _comments.CreateAsync(authorId, request.DiscussionId, request.Content);
-        return CreatedAtAction(nameof(GetCommentById), new { CommentId = response.Id }, response);
+        return CreatedAtAction(nameof(GetCommentById), new { commentId = response.Id }, response);
     }
 
     /// <summary>
     /// Get replies to the comment with the specified ID.
     /// </summary>
     [HttpGet("{parentCommentId}/replies")]
+    [ProducesResponseType(typeof(IEnumerable<CommentDto>), (int)HttpStatusCode.OK)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.InternalServerError)]
+    [ProducesResponseType(typeof(ValidationProblem), (int)HttpStatusCode.BadRequest)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.NotFound)]
     public async Task<IEnumerable<CommentDto>> GetRepliesToComment(
         [FromRoute] Guid parentCommentId,
         [FromQuery, BindRequired] int page,
@@ -61,13 +76,18 @@ public async Task<IEnumerable<CommentDto>> GetRepliesToComment(
     /// Creates a reply to the comment with the specified ID.
     /// </summary>
     [HttpPost("{parentCommentId}/replies")]
+    [ProducesResponseType(typeof(CommentDto), (int)HttpStatusCode.Created)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.InternalServerError)]
+    [ProducesResponseType(typeof(ValidationProblem), (int)HttpStatusCode.BadRequest)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.Forbidden)]
+    [ProducesResponseType(typeof(Problem), (int)HttpStatusCode.NotFound)]
     public async Task<ActionResult<CommentDto>> ReplyToComment([FromRoute] Guid parentCommentId, [FromBody] ReplyRequest request)
     {
         var authorId =
             User.GetUserId()
             ?? throw new ForbiddenException();
 
         var response = await _comments.ReplyToCommentAsync(authorId, parentCommentId, request.Content);
-        return CreatedAtAction(nameof(GetCommentById), new { CommentId = response.Id }, response);
+        return CreatedAtAction(nameof(GetCommentById), new { commentId = response.Id }, response);
     }
 }