Umbraco 10项目中Swashbuckle无法检测自定义API端点的求助

1. 让.NET Core发现类库中的控制器 #

.NET Core默认仅扫描启动项目的程序集来识别控制器，你的自定义API在独立类库中，需要手动将该类库的程序集加入控制器发现列表。在ConfigureServices方法里，找到控制器注册相关代码，添加AddApplicationPart：

public void ConfigureServices(IServiceCollection services)
{
    // 其他服务配置...

    // 新增：将自定义API所在类库的程序集添加到控制器发现范围
    services.AddControllers()
        .AddApplicationPart(typeof(MyEndpointApiController).Assembly);

    services.AddSwaggerGen(options =>
    {
        // 原有的Swagger配置
        options.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "My Endpoint API",
            Version = "v1",
        });
        var basePath = AppDomain.CurrentDomain.BaseDirectory;
        string[] xmlFilenames = new[] { "MyEndpoint.Api.xml", "MyLibrary.Models.xml" };

        options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
        foreach (var filename in xmlFilenames)
        {
            options.IncludeXmlComments(Path.Combine(basePath, filename));
        }
    });
}

2. 可选：过滤Umbraco内置API #

如果只想展示自定义API，不想看到Umbraco自带的Forms API，可以在AddSwaggerGen中添加规则，仅包含自定义程序集的接口：

services.AddSwaggerGen(options =>
{
    // 原有的配置...

    // 获取自定义API所在的程序集
    var customApiAssembly = typeof(MyEndpointApiController).Assembly;
    // 仅保留自定义程序集的API
    options.DocInclusionPredicate((docName, apiDesc) =>
    {
        if (apiDesc.ActionDescriptor is ControllerActionDescriptor controllerActionDesc)
        {
            return controllerActionDesc.ControllerTypeInfo.Assembly == customApiAssembly;
        }
        return false;
    });
});

3. 修正控制器代码的小问题 #

你的控制器代码里有两处笔误，虽然API能运行，但建议修正以避免潜在问题：

• 方法的Public改为小写public
• 返回的OK改为小写Ok

修正后的代码片段：

[Route("api/my-api-endpoint")]
[ApiController]
public class MyEndpointApiController: Controller {
  
    [Route("")]
    [HttpGet]
    [ProducesResponseType(typeof(string), StatusCodes.Status200Ok)]
    public ActionResult Get() {
          return Ok("This is working");
    }
}

4. 确认XML注释文件配置 #

确保自定义类库已生成XML注释文件并复制到输出目录：

• 右键类库项目 → 属性 → 生成 → 勾选「XML文档文件」，设置输出路径为bin\Debug\net6.0\MyEndpoint.Api.xml（和你配置的文件名一致）。

完成以上配置后重启应用，访问/swagger/就能看到你的自定义API端点了。

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