ersatztv/ErsatzTV/Serialization/ApiSecuritySchemeDocumentTransformer.cs

#nullable enable
using ErsatzTV.Filters;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

namespace ErsatzTV.Serialization;

/// <summary>
/// OpenAPI document transformer that declares the components the per-operation transformers reference:
/// the <c>ApiKey</c> security scheme (<c>X-Api-Key</c> request header) used by
/// <see cref="ApiSecurityOperationTransformer" />, and the <c>ValidationProblemDetails</c> schema used
/// by <see cref="ValidationProblemOperationTransformer" /> for documented <c>400</c> responses. Runs on
/// the "v1" document only. See issues #286/#287.
/// </summary>
public static class ApiSecuritySchemeDocumentTransformer
{
    public const string ValidationProblemDetailsSchemaId = "ValidationProblemDetails";
    public const string ProblemDetailsSchemaId = "ProblemDetails";

    public static Task TransformAsync(
        OpenApiDocument document,
        OpenApiDocumentTransformerContext context,
        CancellationToken cancellationToken)
    {
        document.Components ??= new OpenApiComponents();

        document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
        document.Components.SecuritySchemes[ApiSecurityOperationTransformer.SchemeName] = new OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.ApiKey,
            Name = ApiKeyAuthorizationFilter.HeaderName,
            In = ParameterLocation.Header,
            Description =
                "API key sent in the 'X-Api-Key' request header. Required for all mutating requests and, " +
                "under the default posture (Api:RequireKeyForReads=true), for reads as well."
        };

        document.Components.Schemas ??= new Dictionary<string, IOpenApiSchema>();
        if (!document.Components.Schemas.ContainsKey(ValidationProblemDetailsSchemaId))
        {
            document.Components.Schemas[ValidationProblemDetailsSchemaId] = BuildValidationProblemDetailsSchema();
        }

        // The injected 401 (ApiSecurityOperationTransformer) references the ProblemDetails schema. It
        // normally already exists because other actions declare ProducesResponseType(typeof(ProblemDetails)),
        // but self-provision it if absent so the 401 reference never dangles (belt-and-suspenders).
        if (!document.Components.Schemas.ContainsKey(ProblemDetailsSchemaId))
        {
            document.Components.Schemas[ProblemDetailsSchemaId] = BuildProblemDetailsSchema();
        }

        return Task.CompletedTask;
    }

    // The RFC 7807 shape ASP.NET Core returns for a plain ProblemDetails response (the ValidationProblemDetails
    // members minus the "errors" map).
    private static OpenApiSchema BuildProblemDetailsSchema() =>
        new()
        {
            Type = JsonSchemaType.Object,
            Properties = new Dictionary<string, IOpenApiSchema>
            {
                ["type"] = new OpenApiSchema { Type = JsonSchemaType.String | JsonSchemaType.Null },
                ["title"] = new OpenApiSchema { Type = JsonSchemaType.String | JsonSchemaType.Null },
                ["status"] = new OpenApiSchema
                {
                    Type = JsonSchemaType.Integer | JsonSchemaType.Null,
                    Format = "int32"
                },
                ["detail"] = new OpenApiSchema { Type = JsonSchemaType.String | JsonSchemaType.Null },
                ["instance"] = new OpenApiSchema { Type = JsonSchemaType.String | JsonSchemaType.Null }
            }
        };

    // The RFC 7807 shape ASP.NET Core's [ApiController] + FluentValidation return on a model-binding /
    // validation failure: the standard ProblemDetails members plus an "errors" map of field -> messages.
    private static OpenApiSchema BuildValidationProblemDetailsSchema() =>
        new()
        {
            Type = JsonSchemaType.Object,
            Properties = new Dictionary<string, IOpenApiSchema>
            {
                ["type"] = new OpenApiSchema { Type = JsonSchemaType.String | JsonSchemaType.Null },
                ["title"] = new OpenApiSchema { Type = JsonSchemaType.String | JsonSchemaType.Null },
                ["status"] = new OpenApiSchema
                {
                    Type = JsonSchemaType.Integer | JsonSchemaType.Null,
                    Format = "int32"
                },
                ["detail"] = new OpenApiSchema { Type = JsonSchemaType.String | JsonSchemaType.Null },
                ["instance"] = new OpenApiSchema { Type = JsonSchemaType.String | JsonSchemaType.Null },
                ["errors"] = new OpenApiSchema
                {
                    Type = JsonSchemaType.Object,
                    AdditionalProperties = new OpenApiSchema
                    {
                        Type = JsonSchemaType.Array,
                        Items = new OpenApiSchema { Type = JsonSchemaType.String }
                    }
                }
            }
        };
}