Consolidate SwaggerResponses (#147)

src/GeoCop.Api/Controllers/DeliveryController.cs

@@ -44,7 +44,7 @@ public DeliveryController(ILogger<DeliveryController> logger, Context context, I
     [SwaggerResponse(StatusCodes.Status201Created, "The delivery was created successfully.")]
     [SwaggerResponse(StatusCodes.Status400BadRequest, "The server cannot process the request due to invalid or malformed request.", typeof(ValidationProblemDetails), new[] { "application/json" })]
     [SwaggerResponse(StatusCodes.Status404NotFound, "The validation job or mandate could not be found.")]
-    [SwaggerResponse(StatusCodes.Status500InternalServerError, "The server encountered an unexpected condition that prevented it from fulfilling the request.", typeof(ProblemDetails), new[] { "application/json" })]
+    [SwaggerResponse(StatusCodes.Status500InternalServerError, "The server encountered an unexpected condition that prevented it from fulfilling the request. Likely there was an error persisting the assets.", typeof(ProblemDetails), new[] { "application/json" })]
     public async Task<IActionResult> Create(DeliveryRequest declaration)
     {
         logger.LogInformation("Declaration for job with id <{JobId}> requested.", declaration.JobId);
@@ -171,7 +171,7 @@ public async Task<IActionResult> Get([FromQuery] int? mandateId = null)
     [SwaggerResponse(StatusCodes.Status200OK, "The delivery was successfully deleted.")]
     [SwaggerResponse(StatusCodes.Status400BadRequest, "The server cannot process the request due to invalid or malformed request.", typeof(ValidationProblemDetails), new[] { "application/json" })]
     [SwaggerResponse(StatusCodes.Status404NotFound, "The delivery could be found.")]
-    [SwaggerResponse(StatusCodes.Status500InternalServerError, "The server encountered an unexpected condition that prevented it from fulfilling the request.", typeof(ProblemDetails), new[] { "application/json" })]
+    [SwaggerResponse(StatusCodes.Status500InternalServerError, "The server encountered an unexpected condition that prevented it from fulfilling the request. Likely there was an error deleting the assets.", typeof(ProblemDetails), new[] { "application/json" })]
     public IActionResult Delete([FromRoute] int deliveryId)
     {
         logger.LogInformation("Deleting of delivery with id <{DeliveryId}> started.", deliveryId);
@@ -209,7 +209,7 @@ public IActionResult Delete([FromRoute] int deliveryId)
     [SwaggerResponse(StatusCodes.Status200OK, "A file has been downloaded.", typeof(File), new[] { "application/json" })]
     [SwaggerResponse(StatusCodes.Status400BadRequest, "The server cannot process the request due to invalid or malformed request.", typeof(ValidationProblemDetails), new[] { "application/json" })]
     [SwaggerResponse(StatusCodes.Status404NotFound, "The asset could be found.")]
-    [SwaggerResponse(StatusCodes.Status500InternalServerError, "The server encountered an unexpected condition that prevented it from fulfilling the request.", typeof(ProblemDetails), new[] { "application/json" })]
+    [SwaggerResponse(StatusCodes.Status500InternalServerError, "The server encountered an unexpected condition that prevented it from fulfilling the request. Likely the file could not be read.", typeof(ProblemDetails), new[] { "application/json" })]
     public async Task<IActionResult> DownloadAsync([FromRoute] int assetId)
     {
         logger.LogInformation("Downloading asset with id <{AssetId}> started.", assetId);

src/GeoCop.Api/Controllers/UserController.cs

@@ -4,6 +4,7 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Options;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace GeoCop.Api.Controllers;
 
@@ -37,6 +38,7 @@ public UserController(ILogger<UserController> logger, Context context, IOptions<
     /// <returns>The <see cref="User"/> that is currently logged in.</returns>
     [HttpGet]
     [Authorize(Policy = GeocopPolicies.User)]
+    [SwaggerResponse(StatusCodes.Status200OK, "Returns the currently logged in user.", typeof(User), new[] { "application/json" })]
     public async Task<User?> GetAsync()
     {
         var user = await context.GetUserByPrincipalAsync(User);
@@ -58,6 +60,7 @@ public UserController(ILogger<UserController> logger, Context context, IOptions<
     /// <returns>The configured options used for authentication.</returns>
     [HttpGet("auth")]
     [AllowAnonymous]
+    [SwaggerResponse(StatusCodes.Status200OK, "Returns the auth configuration used by the server for token validation.", typeof(BrowserAuthOptions), new[] { "application/json" })]
     public BrowserAuthOptions GetAuthOptions()
     {
         logger.LogInformation("Getting auth options.");

src/GeoCop.Api/Controllers/ValidationController.cs

@@ -91,6 +91,10 @@ public async Task<IActionResult> GetValidationSettings()
     [SwaggerResponse(StatusCodes.Status201Created, "The validation job was successfully created and is now scheduled for execution.", typeof(ValidationJobStatus), new[] { "application/json" })]
     [SwaggerResponse(StatusCodes.Status400BadRequest, "The server cannot process the request due to invalid or malformed request.", typeof(ProblemDetails), new[] { "application/json" })]
     [SwaggerResponse(StatusCodes.Status413PayloadTooLarge, "The file is too large. Max allowed request body size is 200 MB.")]
+    [SwaggerResponse(StatusCodes.Status500InternalServerError,
+        "The server encountered an unexpected condition that prevented it from fulfilling the request. Likely the file could not be written or the file extension is not supported.",
+        typeof(ProblemDetails),
+        new[] { "application/json" })]
     [SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1629:DocumentationTextMustEndWithAPeriod", Justification = "Not applicable for code examples.")]
     public async Task<IActionResult> UploadAsync(ApiVersion version, IFormFile file)
     {

src/GeoCop.Api/Controllers/VersionController.cs

@@ -1,5 +1,6 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
+using Swashbuckle.AspNetCore.Annotations;
 using System.Reflection;
 
 namespace GeoCop.Api.Controllers;
@@ -17,6 +18,7 @@ public class VersionController : ControllerBase
     /// </summary>
     /// <returns>Version string.</returns>
     [HttpGet]
+    [SwaggerResponse(StatusCodes.Status200OK, "Returns the application version.", typeof(string), new[] { "text/plain" })]
     public string Get()
     {
         var assembly = typeof(Program).Assembly;