NSwag项目中使用ApiExplorerSettings控制TypeScript客户端生成

在ASP.NET Core项目中使用NSwag生成TypeScript客户端时，开发者经常需要控制哪些控制器(Controller)应该被包含在生成的客户端代码中。本文将详细介绍如何通过ApiExplorerSettings特性精确控制NSwag的生成范围。

背景介绍

NSwag是一个强大的工具，能够自动从ASP.NET Core Web API生成TypeScript客户端代码。在项目升级到NSwag 14版本后，一些开发者发现之前通过反射选择特定控制器生成客户端的方法不再适用，需要寻找新的解决方案。

解决方案

默认忽略所有控制器

我们可以通过实现IControllerModelConvention接口，在项目启动时自动为所有控制器添加[ApiExplorerSettings(IgnoreApi = true)]特性，从而默认忽略所有控制器的API文档生成。

public class IgnoreApiConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        var apiExplorerSettingAttribute = controller.Attributes
            .FirstOrDefault(x => x is ApiExplorerSettingsAttribute) as ApiExplorerSettingsAttribute;
        
        var hasAttributeEnablingGeneration = apiExplorerSettingAttribute != null 
            && apiExplorerSettingAttribute.IgnoreApi == false;
        
        if (!hasAttributeEnablingGeneration)
        {
            controller.ApiExplorer.IsVisible = false;
        }
    }
}

在启动类中注册约定

在Startup类的ConfigureServices方法中，我们需要检测当前是否由NSwag运行，如果是则应用我们的约定：

public void ConfigureServices(IServiceCollection services)
{
    var entryAssembly = Assembly.GetEntryAssembly();
    var isNswagRunning = entryAssembly?.FullName?.StartsWith("NSwag") ?? false;
    
    services.AddControllersWithViews(options =>
    {
        if (isNswagRunning)
        {
            options.Conventions.Add(new IgnoreApiConvention());
        }
    })
    .AddRazorRuntimeCompilation();
}

显式包含特定控制器

对于需要生成TypeScript客户端的控制器，只需添加[ApiExplorerSettings(IgnoreApi = false)]特性：

[ApiExplorerSettings(IgnoreApi = false)]
[Route("api/[controller]")]
public class MyApiController : ControllerBase
{
    // 控制器方法
}

技术原理

1. ApiExplorerSettings特性：这是ASP.NET Core内置的特性，用于控制API的可见性。当IgnoreApi设置为true时，相关API不会出现在OpenAPI/Swagger文档中。

2. IControllerModelConvention接口：允许我们在应用程序启动时修改控制器的模型，实现批量添加特性的功能。

3. NSwag运行检测：通过检查程序集名称判断当前是否由NSwag运行，避免在生产环境中不必要地修改控制器行为。

最佳实践

1. 明确包含优于排除：采用"默认排除，显式包含"的策略更易于维护，可以避免意外暴露API。

2. 组织控制器：考虑按功能模块组织控制器，并为每个模块创建单独的TypeScript客户端。

3. 版本控制：结合API版本控制，可以更精细地控制不同版本的API文档生成。

4. 自动化测试：添加测试确保只有预期的控制器被包含在客户端生成中。

总结

通过结合ApiExplorerSettings特性和控制器约定，我们可以灵活控制NSwag生成TypeScript客户端的范围。这种方法不仅适用于NSwag 14及以上版本，也符合ASP.NET Core的设计理念，提供了清晰、可维护的API文档生成控制方案。