Blelkes/response codes (#261)

* Fix endpoint documentation and populate responses with more accurate response codes.
Refactored error handling logic into `ErrorResultGeneratorMiddleware`.

* Updated Swagger configuration to improve API documentation ordering and readability.

* Add integration tests.
Moved health check DI registration into separate file.
Updated `Program.cs` to be non-static to support testing.
Added `.runsettings` to configure the test environment.

* Amend runsettings used by pipeline with ASPNETCORE_ENVIRONMENT environment variable.

* Revert "Amend runsettings used by pipeline with ASPNETCORE_ENVIRONMENT environment variable."

This reverts commit 2d1c28d.

* Replace WebApplicationFactory with TestServer.

* Removed unused logger and renamed HealthCheckExtensions.cs

* UserController cleanup.

Author: blelkes-ob

OneBeyond.Studio.Obelisk.sln

@@ -30,6 +30,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OneBeyond.Studio.Obelisk.Do
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "OneBeyond.Studio.Obelisk.Workers", "src\OneBeyond.Studio.Obelisk.Workers\OneBeyond.Studio.Obelisk.Workers.csproj", "{3826B005-74AD-48CA-9CF1-C9BFED6A1196}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OneBeyond.Studio.Obelisk.WebApi.Tests", "src\OneBeyond.Studio.Obelisk.WebApi.Tests\OneBeyond.Studio.Obelisk.WebApi.Tests.csproj", "{672DE642-8FAF-46BC-9272-BED0CFA2AE9F}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -68,6 +70,10 @@ Global
 		{3826B005-74AD-48CA-9CF1-C9BFED6A1196}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{3826B005-74AD-48CA-9CF1-C9BFED6A1196}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{3826B005-74AD-48CA-9CF1-C9BFED6A1196}.Release|Any CPU.Build.0 = Release|Any CPU
+		{672DE642-8FAF-46BC-9272-BED0CFA2AE9F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{672DE642-8FAF-46BC-9272-BED0CFA2AE9F}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{672DE642-8FAF-46BC-9272-BED0CFA2AE9F}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{672DE642-8FAF-46BC-9272-BED0CFA2AE9F}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

src/OneBeyond.Studio.Obelisk.Application/Features/Users/Dto/CreateUserDto.cs

@@ -2,7 +2,7 @@ namespace OneBeyond.Studio.Obelisk.Application.Features.Users.Dto;
 
 public sealed record CreateUserDto
 {
-    public string Email { get; private init; } = default!;
-    public string UserName { get; private init; } = default!;
-    public string? RoleId { get; private init; }
+    public required string Email { get; init; }
+    public required string UserName { get; init; }
+    public string? RoleId { get; init; }
 }

src/OneBeyond.Studio.Obelisk.WebApi.Tests/Middlewares/ErrorResultGeneratorMiddlewareTests.cs

@@ -0,0 +1,71 @@
+using System.Net;
+using System.Net.Http.Json;
+using FluentAssertions;
+using FluentAssertions.Execution;
+using Microsoft.AspNetCore.Mvc;
+using OneBeyond.Studio.Obelisk.WebApi.Middlewares;
+
+namespace OneBeyond.Studio.Obelisk.WebApi.Tests.Middlewares;
+
+public class ErrorResultGeneratorMiddlewareTests : IClassFixture<TestServerFixture>
+{
+    private readonly HttpClient _client;
+
+    public ErrorResultGeneratorMiddlewareTests(TestServerFixture testServer)
+    {
+        _client = testServer.Client;
+    }
+
+    [Fact]
+    public async Task InvokeAsync_NoException_Succeeds()
+    {
+        // Act
+        var response = await _client.GetAsync("/health/live");
+
+        // Assert
+        response.IsSuccessStatusCode.Should().BeTrue();
+    }
+
+    [Fact]
+    public async Task InvokeAsync_ValidationException_ReturnsBadRequest()
+    {
+        // Arrange
+        var invalidRequest = new { };
+
+        // Act
+        var response = await _client.PostAsJsonAsync("/api/users/v1", invalidRequest);
+
+        // Assert
+        using var _ = new AssertionScope();
+        response.StatusCode.Should().Be(HttpStatusCode.BadRequest);
+
+        var problemDetails = await response.Content.ReadFromJsonAsync<ProblemDetails>();
+        problemDetails?.Title.Should().Be("One or more validation errors occurred.");
+
+        var traceId = problemDetails?.Extensions[ErrorResultGeneratorMiddleware.TraceIdKey]?.ToString();
+        traceId.Should().NotBeNullOrEmpty();
+    }
+
+    [Fact]
+    public async Task InvokeAsync_EntityNotFoundException_ReturnsNotFound()
+    {
+        // Arrange
+        var nonExistentId = Guid.NewGuid();
+
+        // Act
+        var response = await _client.GetAsync($"/api/users/v1/{nonExistentId}");
+
+        // Assert
+        using var _ = new AssertionScope();
+        response.StatusCode.Should().Be(HttpStatusCode.NotFound);
+
+        var mediaType = response.Content.Headers.ContentType?.MediaType;
+        mediaType.Should().Be(ErrorResultGeneratorMiddleware.ProblemContent);
+
+        var problemDetails = await response.Content.ReadFromJsonAsync<ProblemDetails>();
+        problemDetails?.Title.Should().Be("Not Found");
+
+        var traceId = problemDetails?.Extensions[ErrorResultGeneratorMiddleware.TraceIdKey]?.ToString();
+        traceId.Should().NotBeNullOrEmpty();
+    }
+}

src/OneBeyond.Studio.Obelisk.WebApi.Tests/OneBeyond.Studio.Obelisk.WebApi.Tests.csproj

@@ -0,0 +1,31 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="FluentAssertions" Version="6.12.0" />
+    <PackageReference Include="coverlet.collector" Version="6.0.0" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="8.0.20" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+    <PackageReference Include="Moq" Version="4.20.72" />
+    <PackageReference Include="xunit" Version="2.5.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.3" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\OneBeyond.Studio.Obelisk.WebApi\OneBeyond.Studio.Obelisk.WebApi.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+</Project>

src/OneBeyond.Studio.Obelisk.WebApi.Tests/TestAuthHandler.cs

@@ -0,0 +1,36 @@
+using System.Security.Claims;
+using System.Text.Encodings.Web;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace OneBeyond.Studio.Obelisk.WebApi.Tests;
+
+internal sealed class TestAuthHandler : AuthenticationHandler<AuthenticationSchemeOptions>
+{
+    public const string AuthenticationType = "Test";
+    public const string AuthenticationScheme = "Test";
+
+    public TestAuthHandler(
+        IOptionsMonitor<AuthenticationSchemeOptions> options,
+        ILoggerFactory logger,
+        UrlEncoder encoder)
+        : base(options, logger, encoder)
+    {
+    }
+
+    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
+    {
+        var claims = new[]
+        {
+            new Claim(ClaimTypes.Name, "TestUser"),
+            new Claim(ClaimTypes.Role, "Administrator")
+        };
+        var identity = new ClaimsIdentity(claims, AuthenticationType);
+        var principal = new ClaimsPrincipal(identity);
+        var ticket = new AuthenticationTicket(principal, AuthenticationScheme);
+
+        var result = AuthenticateResult.Success(ticket);
+        return Task.FromResult(result);
+    }
+}

src/OneBeyond.Studio.Obelisk.WebApi.Tests/TestServerFixture.cs

@@ -0,0 +1,99 @@
+using MediatR;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Diagnostics.HealthChecks;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.TestHost;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Options;
+using Moq;
+using OneBeyond.Studio.Application.SharedKernel.Entities.Queries;
+using OneBeyond.Studio.Application.SharedKernel.Repositories.Exceptions;
+using OneBeyond.Studio.Obelisk.Application.Features.Users.Dto;
+using OneBeyond.Studio.Obelisk.Domain.Features.Users.Entities;
+using OneBeyond.Studio.Obelisk.WebApi.Controllers;
+using OneBeyond.Studio.Obelisk.WebApi.Extensions;
+using OneBeyond.Studio.Obelisk.WebApi.Helpers;
+using OneBeyond.Studio.Obelisk.WebApi.Middlewares;
+
+namespace OneBeyond.Studio.Obelisk.WebApi.Tests;
+
+public sealed class TestServerFixture : IAsyncLifetime
+{
+    public IHost Host { get; private set; } = default!;
+    public HttpClient Client { get; private set; } = default!;
+
+    public async Task InitializeAsync()
+    {
+        Host = await new HostBuilder()
+            .ConfigureWebHost(webBuilder =>
+            {
+                webBuilder
+                    .UseTestServer()
+                    .ConfigureServices((context, services) =>
+                    {
+                        var options = new ClientApplicationOptions { Url = "fake" };
+                        services.TryAddSingleton(Options.Create(options));
+
+                        var mediatorMock = new Mock<IMediator>();
+                        mediatorMock
+                            .Setup(mediator => mediator.Send(It.IsAny<GetById<GetUserDto, UserBase, Guid>>(),It.IsAny<CancellationToken>()))
+                            .ThrowsAsync(new EntityNotFoundException<User, Guid>(Guid.NewGuid()));
+
+                        services.TryAddTransient(_ => mediatorMock.Object);
+                        services.TryAddTransient<ClientApplicationLinkGenerator, ClientApplicationLinkGenerator>();
+
+                        services.AddAuthentication(options =>
+                        {
+                            options.DefaultAuthenticateScheme = TestAuthHandler.AuthenticationScheme;
+                        })
+                        .AddScheme<AuthenticationSchemeOptions, TestAuthHandler>(TestAuthHandler.AuthenticationScheme, _ => { });
+
+                        services.AddControllers()
+                            .AddApplicationPart(typeof(UsersController).Assembly);
+
+                        services.AddApiVersioning();
+                        services.AddHealthChecks()
+                            .AddCheck(HealthCheckExtensions.SelfCheck, () => HealthCheckResult.Healthy());
+                    })
+                    .Configure(app =>
+                    {
+                        app.UseRouting();
+                        app.Use(async (context, next) =>
+                        {
+                            using var activity = new System.Diagnostics.Activity("HttpRequest");
+                            activity.Start();
+                            await next();
+                        });
+                        app.UseMiddleware<ErrorResultGeneratorMiddleware>();
+                        app.UseAuthentication();
+                        app.UseAuthorization();
+                        app.UseEndpoints(endpoints =>
+                        {
+                            endpoints.MapControllers();
+                            endpoints.MapHealthChecks("/health/live", new HealthCheckOptions
+                            {
+                                Predicate = registration => registration.Name.Contains(HealthCheckExtensions.SelfCheck)
+                            });
+                        });
+                    });
+            })
+            .StartAsync();
+
+        Client = Host.GetTestClient();
+    }
+
+    public async Task DisposeAsync()
+    {
+        Client?.Dispose();
+
+        if (Host is not null)
+        {
+            await Host.StopAsync();
+            Host.Dispose();
+        }
+    }
+}

src/OneBeyond.Studio.Obelisk.WebApi/Controllers/QBasedController.cs

@@ -22,78 +22,51 @@ public abstract class QBasedController<TEntityGetDTO, TEntityListDTO, TEntity, T
 {
     protected QBasedController(IMediator mediator)
     {
-        EnsureArg.IsNotNull(mediator, nameof(mediator));
-
-        Mediator = mediator;
+        Mediator = EnsureArg.IsNotNull(mediator, nameof(mediator));
     }
 
     protected IMediator Mediator { get; }
 
     /// <summary>
     /// Gets a list of entities.
     /// </summary>
-    /// <param name="queryParameters"></param>
-    /// <param name="query"></param>
-    /// <param name="cancellationToken"></param>
-    /// <response code="200">If the list of entities returned</response>
-    /// <response code="400">If the request is invalid</response>
+    /// <param name="queryParameters">The <see cref="ListRequest"/> representation of the query parameters to apply.</param>
+    /// <param name="query">TODO!</param>
+    /// <param name="cancellationToken"><see cref="CancellationToken"/> token to cancel the operation.</param>
+    /// <returns><see cref="OkResult"/> with a <see cref="PagedList{TEntity}"/> of entities.</returns>
+    /// <response code="200">Returns a paged list of entities.</response>
+    /// <response code="400">If a query parameter is invalid.</response>
+    [HttpGet]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
-    [HttpGet]
-    public virtual async Task<IActionResult> Get(
+    public virtual async Task<ActionResult<PagedList<TEntityListDTO>>> Get(
         [FromQuery] ListRequest queryParameters,
         Dictionary<string, IReadOnlyCollection<string>> query,
         CancellationToken cancellationToken)
     {
         query = ControllerHelpers.CleanQuery(query);
-        var result = await ListAsync(queryParameters, query, cancellationToken);
-        return Json(result);
+        var request = queryParameters.ToListQuery<TEntityListDTO, TEntity, TEntityId>(query);
+        var result = await Mediator.Send(request, cancellationToken);
+        return result;
     }
 
     /// <summary>
     /// Gets a specified entity.
     /// </summary>
-    /// <param name="id" example="3fa85f64-5717-4562-b3fc-2c963f66afa6">The ID of the entity</param>
-    /// <param name="cancellationToken"></param>
-    /// <response code="200">If the entity is returned</response>
-    /// <response code="400">If the entity with the specified ID does not exist</response>
+    /// <param name="id" example="3fa85f64-5717-4562-b3fc-2c963f66afa6">The ID of the entity.</param>
+    /// <param name="cancellationToken"><see cref="CancellationToken"/> token to cancel the operation.</param>
+    /// <returns><see cref="OkResult"/> with the <typeparamref name="TEntityGetDTO"/>.</returns>
+    /// <response code="200">Returns the specified entity.</response>
+    /// <response code="404">If the entity does not exist.</response>
+    /// <response code="400">If the ID is invalid.</response>
+    [HttpGet("{id}")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
-    [HttpGet("{id}")]
-    public virtual async Task<IActionResult> GetById(
-        TEntityId id,
-        CancellationToken cancellationToken)
-    {
-        var result = await GetByIdAsync<TEntityGetDTO>(id, cancellationToken);
-        return result is not null
-            ? Json(result)
-            : BadRequest("Not found");
-    }
-
-    protected virtual Task<PagedList<TEntityListDTO>> ListAsync(
-        ListRequest queryParameters,
-        Dictionary<string, IReadOnlyCollection<string>> query,
-        CancellationToken cancellationToken)
-        => Mediator.Send(
-            queryParameters.ToListQuery<TEntityListDTO, TEntity, TEntityId>(query),
-            cancellationToken);
-
-    protected virtual Task<TDTO> GetByIdAsync<TDTO>(
-        TEntityId aggregateRootId,
-        CancellationToken cancellationToken)
-        => Mediator.Send(
-            new GetById<TDTO, TEntity, TEntityId>(aggregateRootId),
-            cancellationToken);
-}
-
-public abstract class QBasedController<TEntityListDTO, TEntity, TEntityId>
-    : QBasedController<TEntityListDTO, TEntityListDTO, TEntity, TEntityId>
-    where TEntity : DomainEntity<TEntityId>
-    where TEntityListDTO : new()
-{
-    protected QBasedController(
-        IMediator mediator)
-        : base(mediator)
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public virtual async Task<ActionResult<TEntityGetDTO>> GetById(TEntityId id, CancellationToken cancellationToken)
     {
+        var request = new GetById<TEntityGetDTO, TEntity, TEntityId>(id);
+        var result = await Mediator.Send(request, cancellationToken);
+        return result;
     }
 }