向IdentityServer4(.NET Core 6)添加SwaggerUI遇组件为空问题

你的问题核心是Swagger未扫描到自定义LocalApi控制器的端点，导致生成的OpenAPI规范里paths和components为空，最终显示"No operations defined in spec!"。以下是针对性的解决步骤：

1. 给控制器添加正确的路由特性 #

Swagger依赖路由信息识别API端点，所有LocalApi控制器必须配置[Route]特性，示例：

[ApiController]
[Route("api/[controller]")] // 必须添加路由特性
[Authorize(LocalApi.PolicyName)]
public class MyLocalApiController : ControllerBase
{
    [HttpGet("test")]
    public IActionResult GetTest()
    {
        return Ok("Local API Response");
    }
}

2. 调整中间件执行顺序 #

当前中间件顺序存在逻辑问题，正确顺序需保证认证、IdentityServer与Swagger的加载顺序合理：

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

// 先启用IdentityServer核心服务
app.UseIdentityServer();

// 再启用Swagger相关中间件，指定文档端点
app.UseSwagger();
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "Bev360.IDP v1");
});

app.MapRazorPages().RequireAuthorization();

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
});

3. 配置SwaggerGen适配LocalApi认证 #

让Swagger识别LocalApi的授权策略，添加安全定义与全局安全要求：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "Bev360.IDP Local API", Version = "v1" });

    // 定义LocalApi认证方案
    options.AddSecurityDefinition("LocalApi", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.ApiKey,
        Name = "Authorization",
        In = ParameterLocation.Header,
        Description = "使用Bearer Token格式：Bearer {token}"
    });

    // 全局应用安全要求
    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "LocalApi" }
            },
            Array.Empty<string>()
        }
    });
});

4. 确保控制器可被扫描到 #

• 控制器类必须是public访问修饰符，Swagger不会扫描非公开控制器
• 若控制器在单独程序集中，需显式指定扫描范围：

builder.Services.AddEndpointsApiExplorer(options =>
{
    options.AssemblyNames.Add(typeof(MyLocalApiController).Assembly.GetName().Name);
});

按以上步骤调整后重启项目，Swagger即可正确识别LocalApi端点，生成包含完整paths和components的OpenAPI规范。

内容的提问来源于stack exchange，提问作者Shawn