HealthReport object structure produced by health checks endpoint freezes Swagger docs page

Question

I enabled health checks for my .Net 5 Web API project

public sealed class Startup
{
    public void ConfigureServices(IServiceCollection serviceCollection)
    {
        serviceCollection.AddHealthChecks();

        // ...
    }

    public void Configure(IApplicationBuilder applicationBuilder, IWebHostEnvironment webHostEnvironment)
    {
        // ...

        applicationBuilder.UseHealthChecks("/health");

        // ...
    }
}

Unfortunately the health endpoint does not appear in the swagger docs. That's why I created an additional controller

[ApiController]
[Route("[controller]")]
public sealed class HealthController : ControllerBase
{
    private readonly HealthCheckService _healthCheckService;

    public HealthController(HealthCheckService healthCheckService)
    {
        _healthCheckService = healthCheckService;
    }

    [HttpGet]
    public async Task<ActionResult<HealthReport>> GetHealthIndication()
    {
        HealthReport healthReport = await _healthCheckService.CheckHealthAsync();

        if (healthReport.Status == HealthStatus.Healthy)
        {
            return Ok(healthReport);
        }

        int serviceUnavailableStatusCode = (int) HttpStatusCode.ServiceUnavailable;
        
        return StatusCode(serviceUnavailableStatusCode, healthReport);
    }
}

When running the application Swagger generated a lot of models. When opening the health endpoint the page freezes for multiple seconds because it has to load the HealthReport object structure.

• I think it is not fine that an API with a single endpoint freezes because of this ... any suggestions for this?

• Do I even have to create my own controller, aren't there any integrations yet? I'm looking for a solution like .UseHealthChecks(HealthController.GetHealthIndication)

Answer 1

TLDR;

Add schema mapping for the Exception class in Swagger configuration.

services.AddSwaggerGen(c =>
            {
                c.MapType<Exception>(() => new OpenApiSchema { Type = "object" });
            });

This code would convert Schema with Exception class as an object, thus the behavior you are facing at the client-side would minimize.

---

Explanation:

Root Cause: Swagger freezes because the swagger javascript client is trying to create a sample model based on schema fetched from swagger json.

If you look at the Exception class, it contains a large number of nested properties and types. If we instruct the swagger generator to treat the Exception class as a simple object in a created JSON file, the client would not have to spend time creating nested objects. (or you can include TimeSpan class in this conversion as well).

There are multiple ways to solve this issue:

1. As mentioned above simply instruct the Swagger generator to map type at config level itself.
2. If you want to create schema based on specific Action (Operation in Swagger context) or Controller (Document in Swagger context), then you can implement respective filters and modify Swagger Document content on the fly. https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/README.md#override-schema-for-specific-types
3. Create your own Response model: This makes sense because over time schema of HealthReport could change and thus the output of service could change without realizing it over longer time.

---

Do I even have to create my own controller, aren't there any integrations yet? I'm looking for a solution.UseHealthChecks(HealthController.GetHealthIndication)

Swashbuckle (Swagger codegen and UI) uses Reflection and Assembly documentation (.xml files) to create swagger documents, thus it is won't scan other assemblies for controllers.