FastEndpoints项目中集成Swagger Basic认证的解决方案

背景介绍

FastEndpoints是一个高性能的.NET Web API框架，它提供了简洁的API开发体验。在实际开发中，我们经常需要为API接口添加认证机制，而Basic认证是最基础也最常用的一种认证方式。本文将详细介绍如何在FastEndpoints项目中配置Swagger UI，使其支持Basic认证。

问题分析

当开发者尝试在FastEndpoints项目中集成Swagger Basic认证时，可能会遇到"OpenAPI/Swagger文档'v1'多次注册"的错误。这是因为FastEndpoints已经内置了Swagger支持，而开发者又手动添加了OpenApiDocument配置，导致文档被重复注册。

解决方案

1. 配置Swagger安全定义

首先需要在项目中添加Swagger的安全定义配置。以下是完整的配置代码示例：

builder.Services.AddSwaggerGen(c =>
{
    c.AddSecurityDefinition("basic", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "basic",
        In = ParameterLocation.Header,
        Description = "Basic Authorization header using the Bearer scheme."
    });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "basic"
                }
            },
            Array.Empty<string>()
        }
    });
});

这段代码做了两件事：

1. 定义了一个名为"basic"的安全方案，类型为HTTP Basic认证
2. 添加了一个全局的安全要求，确保所有API都需要Basic认证

2. 配置FastEndpoints

FastEndpoints有自己的配置方式，需要确保与Swagger配置兼容：

builder.Services.AddFastEndpoints(o =>
{
    o.SourceGeneratorDiscoveredTypes = DiscoveredTypes.All;
});

3. 启用Swagger UI

最后启用Swagger中间件：

app.UseFastEndpoints(c =>
{
    c.Endpoints.RoutePrefix = "api";
    c.Versioning.Prefix = "v";
    c.Versioning.DefaultVersion = 1;
});

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

实现原理

1. 安全定义：AddSecurityDefinition方法告诉Swagger UI如何显示认证输入框，这里配置为Basic认证方式。

2. 安全要求：AddSecurityRequirement方法将安全方案应用到所有API端点，确保它们都需要认证。

3. FastEndpoints集成：FastEndpoints会自动扫描项目中的端点并生成OpenAPI文档，我们只需要确保Swagger配置与其兼容即可。

注意事项

1. 不要重复调用AddOpenApiDocument或AddSwaggerDocument，因为FastEndpoints已经处理了文档生成。

2. 在生产环境中，应该谨慎启用Swagger UI，或者添加额外的访问控制。

3. Basic认证虽然简单，但不适合高安全性要求的场景，建议考虑更安全的认证方式如JWT。

进阶配置

如果需要更细粒度的控制，可以为特定端点配置不同的认证要求：

public class MyEndpoint : Endpoint<MyRequest, MyResponse>
{
    public override void Configure()
    {
        Post("/my-endpoint");
        Description(b => b
            .ProducesProblem(401)
            .WithTags("Special")
            .RequireAuthorization());
    }
}

通过这种方式，可以灵活地为不同端点设置不同的安全要求。

总结

在FastEndpoints项目中集成Swagger Basic认证并不复杂，关键在于理解框架已经提供的功能和避免重复配置。本文提供的解决方案既保持了FastEndpoints的高效特性，又增加了Basic认证支持，为API开发和测试提供了便利。