NSwag中如何选择性生成TypeScript客户端代码

在ASP.NET Core项目中使用NSwag生成TypeScript客户端时，开发者经常需要控制哪些Controller应该被包含在生成的客户端代码中。本文将详细介绍如何通过API Explorer设置来实现这一需求。

默认行为与需求背景

NSwag默认会扫描项目中所有的Controller并为其生成TypeScript客户端代码。但在实际开发中，我们可能只需要为部分API接口生成客户端代码，例如：

• 前端只需要调用特定的API子集
• 项目中同时包含前后端API和纯后端API
• 需要按模块划分客户端代码

解决方案：使用ApiExplorerSettings特性

ASP.NET Core提供了ApiExplorerSettings特性，可以控制API是否应该被文档工具(如Swagger/NSwag)发现和展示。

基本用法

最简单的做法是在不需要生成客户端代码的Controller上添加[ApiExplorerSettings(IgnoreApi = true)]特性：

[ApiExplorerSettings(IgnoreApi = true)]
public class InternalApiController : ControllerBase
{
    // 这个Controller不会被NSwag处理
}

反向选择模式

如果需要生成的Controller较少，可以采用"默认忽略，显式包含"的模式：

1. 首先通过约定忽略所有Controller
2. 然后显式标记需要生成的Controller

// 需要生成的Controller添加此特性
[ApiExplorerSettings(IgnoreApi = false)] 
public class PublicApiController : ControllerBase
{
    // 这个Controller会被NSwag处理
}

实现全局忽略约定

为了简化管理，可以通过实现IControllerModelConvention接口创建全局约定：

public class IgnoreApiConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        // 检查是否显式设置了IgnoreApi=false
        var explicitInclude = controller.Attributes
            .OfType<ApiExplorerSettingsAttribute>()
            .Any(x => !x.IgnoreApi);
        
        if (!explicitInclude)
        {
            // 默认忽略
            controller.ApiExplorer.IsVisible = false;
        }
    }
}

然后在Startup中注册这个约定：

services.AddControllersWithViews(options =>
{
    options.Conventions.Add(new IgnoreApiConvention());
});

运行时条件判断

有时我们可能只在NSwag生成客户端时需要应用这些规则，可以通过检查程序集名称来实现条件判断：

var isNswagRunning = Assembly.GetEntryAssembly()?
    .FullName?.StartsWith("NSwag") ?? false;

if (isNswagRunning)
{
    options.Conventions.Add(new IgnoreApiConvention());
}

最佳实践建议

1. 明确区分公共API和内部API：为需要生成客户端的API创建专门的Controller或标记特性

2. 保持一致性：在整个项目中采用统一的策略（默认包含或默认排除）

3. 文档说明：在项目文档中记录API的可见性策略，方便团队成员理解

4. 考虑API版本控制：如果需要支持多版本API，可以结合ApiVersion特性使用

通过这种方式，开发者可以精细控制NSwag生成的TypeScript客户端代码范围，避免生成不必要的客户端代码，保持前端项目的整洁性。