ASP.NET Core 3.1 Swagger报No operations defined in spec不显示控制器

我在使用ASP.NET Core 3.1集成Swagger时，界面提示“No operations defined in spec!”，无法正常显示控制器下的接口。我尝试查阅了多个相关解决方案，都没能解决问题。

Startup.cs文件代码 #

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddCommonService(Configuration);
    services.AddSecurityServiceRepositories();
    services.AddSwaggerService();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseSwaggerService();
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseHttpsRedirection();
    app.UseRouting();
    app.UseStaticFiles();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
    //app.UseMvc();
}

仓储注册服务类代码 #

namespace Microsoft.Extensions.DependencyInjection
{
    public static class SecurityServiceRepositoryCollectionExtension
    {
        public static IServiceCollection AddSecurityServiceRepositories(this IServiceCollection services)
        {
            services.AddTransient<IUserRepository, UserRepository>();
            return services;
        }
    }
}

Swagger服务扩展类代码 #

namespace Microsoft.Extensions.DependencyInjection
{
    public static class SwaggerServiceExtension
    {
        public static IServiceCollection AddSwaggerService(this IServiceCollection services)
        {
            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "Sample API",
                    Version = "v1",
                    Description = "REST API for Sample "
                });
                options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                {
                    Description = @"JWT Authorization header using the Bearer scheme. \r\n\r
                      Enter 'Bearer' [space] and then your token in the text input below.
                      \r\n\r
Example: 'Bearer 12345abcdef'",
                    Name = "Authorization",
                    In = ParameterLocation.Header,
                    Type = SecuritySchemeType.ApiKey,
                    Scheme = "Bearer"
                });
                options.AddSecurityRequirement(new OpenApiSecurityRequirement()
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference
                            {
                                Type = ReferenceType.SecurityScheme,
                                Id = "Bearer"
                            },
                            Scheme = "oauth2",
                            Name = "Bearer",
                            In = ParameterLocation.Header
                        },
                        new List<string>()
                    }
                });
            });
            return services;
        }
        public static IApplicationBuilder UseSwaggerService(this IApplicationBuilder app)
        {
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "Sample  Api V1");
            });

            return app;
        }
    }
}

控制器代码 #

[Route("api/[controller]")]
[ApiController]
public class UserController : SecuredRepositoryController<IUserRepository>
{
    public UserController(IUserRepository repository) : base(repository) { }

    [HttpPost("register-user")]
    // [Route("register-user")] 我也试过该路由配置
    [AllowAnonymous]
    [ProducesResponseType(typeof(User), 200)]
    public async Task<IActionResult> AddNewUser([FromBody] User user)
    {
        try
        {
            var result = await this.Repository.RegisterUser(user);
            return Ok(result);
        }
        catch (Exception ex)
        {
            return StatusCode(500, ex.Message);
        }
    }
}

当前故障表现 #

Swagger UI显示效果如下，未加载出控制器接口：

故障排查与解决方案 #

按优先级依次检查调整即可：

• 中间件顺序错误
  你当前将UseSwaggerService放在了配置最开头，正确的顺序必须放在UseRouting之后、UseAuthorization之前，修改Configure方法的顺序：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseRouting();
    // Swagger中间件移到此处
    app.UseSwaggerService();
    app.UseAuthorization();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

• 基类控制器配置问题
  检查你继承的SecuredRepositoryController基类是否为public修饰符、是否正确继承了ControllerBase，如果基类是内部类、或者没有正确继承Controller基类，会导致Swagger无法识别控制器。
• SwaggerGen遗漏XML扫描配置
  如果你项目开启了XML文档文件生成，需要在AddSwaggerGen中添加XML读取配置，否则部分场景下Swagger会扫描不到接口：

// 在AddSwaggerGen的options配置块中添加
var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath, true);

同时右键项目→属性→生成，勾选「XML文档文件」，输出路径填写对应运行时版本的输出目录即可。

• 路由与特性冲突检查
  确认你的项目没有全局路由前缀覆盖了控制器的路由配置，也没有[NonAction]、[ApiExplorerSettings(IgnoreApi = true)]这类忽略接口的特性标记在控制器或Action上。

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