docs(api): document collection REST response codes

Refs #35

ErsatzTV/Controllers/Api/CollectionController.cs

@@ -5,6 +5,7 @@ using ErsatzTV.Core;
 using ErsatzTV.Extensions;
 using ErsatzTV.Filters;
 using MediatR;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 
 namespace ErsatzTV.Controllers.Api;
@@ -17,6 +18,7 @@ public class CollectionController(IMediator mediator) : ControllerBase
     [Tags("Collections")]
     [EndpointSummary("Get all collections")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<MediaCollectionViewModel>), StatusCodes.Status200OK)]
     public async Task<List<MediaCollectionViewModel>> GetAll(CancellationToken cancellationToken) =>
         await mediator.Send(new GetAllCollections(), cancellationToken);
 
@@ -24,6 +26,8 @@ public class CollectionController(IMediator mediator) : ControllerBase
     [Tags("Collections")]
     [EndpointSummary("Get a collection by id")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(MediaCollectionViewModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
     {
         Option<MediaCollectionViewModel> result = await mediator.Send(new GetCollectionById(id), cancellationToken);
@@ -34,6 +38,9 @@ public class CollectionController(IMediator mediator) : ControllerBase
     [Tags("Collections")]
     [EndpointSummary("Create a collection")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(MediaCollectionViewModel), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Create(
         [Required] [FromBody] CreateCollectionRequest request,
         CancellationToken cancellationToken)
@@ -47,6 +54,9 @@ public class CollectionController(IMediator mediator) : ControllerBase
     [Tags("Collections")]
     [EndpointSummary("Update a collection")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(MediaCollectionViewModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Update(
         int id,
         [Required] [FromBody] UpdateCollectionRequest request,
@@ -69,6 +79,9 @@ public class CollectionController(IMediator mediator) : ControllerBase
     [Tags("Collections")]
     [EndpointSummary("Delete a collection")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Delete(int id, CancellationToken cancellationToken)
     {
         Either<BaseError, Unit> result = await mediator.Send(new DeleteCollection(id), cancellationToken);
@@ -79,6 +92,9 @@ public class CollectionController(IMediator mediator) : ControllerBase
     [Tags("Collections")]
     [EndpointSummary("Add items to a collection")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> AddItems(
         int id,
         [Required] [FromBody] AddItemsToCollectionRequest request,
@@ -92,6 +108,9 @@ public class CollectionController(IMediator mediator) : ControllerBase
     [Tags("Collections")]
     [EndpointSummary("Remove an item from a collection")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> RemoveItem(int id, int mediaItemId, CancellationToken cancellationToken)
     {
         Either<BaseError, Unit> result = await mediator.Send(

ErsatzTV/Controllers/Api/SmartCollectionController.cs

@@ -6,6 +6,7 @@ using ErsatzTV.Core.Api.SmartCollections;
 using ErsatzTV.Extensions;
 using ErsatzTV.Filters;
 using MediatR;
+using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 
 namespace ErsatzTV.Controllers.Api;
@@ -18,6 +19,7 @@ public class SmartCollectionController(IMediator mediator) : ControllerBase
     [Tags("Smart Collections")]
     [EndpointSummary("Get all smart collections")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(List<SmartCollectionResponseModel>), StatusCodes.Status200OK)]
     public async Task<List<SmartCollectionResponseModel>> GetAll(CancellationToken cancellationToken) =>
         await mediator.Send(new GetAllSmartCollectionsForApi(), cancellationToken);
 
@@ -25,6 +27,8 @@ public class SmartCollectionController(IMediator mediator) : ControllerBase
     [Tags("Smart Collections")]
     [EndpointSummary("Get a smart collection by id")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(SmartCollectionViewModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
     public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
     {
         Option<SmartCollectionViewModel> result =
@@ -36,6 +40,9 @@ public class SmartCollectionController(IMediator mediator) : ControllerBase
     [Tags("Smart Collections")]
     [EndpointSummary("Create a smart collection")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(SmartCollectionViewModel), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Create(
         [Required] [FromBody] CreateSmartCollectionRequest request,
         CancellationToken cancellationToken)
@@ -49,6 +56,9 @@ public class SmartCollectionController(IMediator mediator) : ControllerBase
     [Tags("Smart Collections")]
     [EndpointSummary("Update a smart collection")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(typeof(SmartCollectionViewModel), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Update(
         int id,
         [Required] [FromBody] UpdateSmartCollectionRequest request,
@@ -72,6 +82,9 @@ public class SmartCollectionController(IMediator mediator) : ControllerBase
     [Tags("Smart Collections")]
     [EndpointSummary("Delete a smart collection")]
     [EndpointGroupName("general")]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Delete(int id, CancellationToken cancellationToken)
     {
         Either<BaseError, Unit> result = await mediator.Send(new DeleteSmartCollection(id), cancellationToken);