NSwag中处理API路径前缀的最佳实践

背景介绍

在ASP.NET Core Web API开发中，我们经常使用NSwag来生成OpenAPI/Swagger文档和客户端代码。一个常见的需求是需要处理API路径中的前缀，特别是在多环境部署场景下。本文将详细介绍如何在NSwag中优雅地处理API路径前缀问题。

问题场景

在开发过程中，我们可能会遇到以下典型场景：

1. 本地开发时API路径带有"/api"前缀
2. 部署到云环境(如Azure API Management)时需要移除或修改这个前缀
3. 生成客户端代码时需要确保路径一致性

直接修改路径可能会导致键冲突，特别是在存在相同路径但不同前缀的情况下(如"/api/roles"和"/roles")。

解决方案

NSwag提供了IDocumentProcessor接口，允许我们在文档生成过程中对OpenAPI文档进行自定义处理。这是处理路径前缀问题的理想切入点。

实现自定义文档处理器

public sealed class ApiPathPrefixProcessor : IDocumentProcessor
{
    public void Process(DocumentProcessorContext context)
    {
        // 创建新路径字典，移除所有路径中的"/api"前缀
        var newPaths = context.Document.Paths
            .ToDictionary(
                item => item.Key.Replace("/api", string.Empty, StringComparison.OrdinalIgnoreCase),
                item => item.Value
            );

        // 清空原有路径并添加处理后的新路径
        context.Document.Paths.Clear();
        foreach (var (path, pathItem) in newPaths)
        {
            context.Document.Paths.Add(path, pathItem);
        }

        // 添加服务器配置，保留原始API前缀信息
        context.Document.Servers.Add(new OpenApiServer { Url = "/api" });
    }
}

注册处理器

在Startup.cs或Program.cs中注册自定义处理器：

services.AddOpenApiDocument(settings =>
{
    // 确保处理器最先执行
    settings.DocumentProcessors.Insert(0, new ApiPathPrefixProcessor());
});

实现细节解析

1. 路径处理：使用字典转换确保路径修改后的唯一性
2. 大小写处理：使用StringComparison.OrdinalIgnoreCase确保大小写不敏感
3. 执行顺序：通过Insert(0,...)确保处理器最先执行
4. 服务器配置：保留原始API前缀信息，供客户端生成使用

进阶应用

多环境支持

我们可以扩展处理器，使其支持不同环境的路径配置：

public class EnvironmentAwarePathProcessor : IDocumentProcessor
{
    private readonly IWebHostEnvironment _env;

    public EnvironmentAwarePathProcessor(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void Process(DocumentProcessorContext context)
    {
        var prefix = _env.IsDevelopment() ? "/api" : string.Empty;
        
        var newPaths = context.Document.Paths
            .ToDictionary(
                item => item.Key.Replace("/api", prefix, StringComparison.OrdinalIgnoreCase),
                item => item.Value
            );

        context.Document.Paths.Clear();
        foreach (var (path, pathItem) in newPaths)
        {
            context.Document.Paths.Add(path, pathItem);
        }
    }
}

客户端生成控制

在NSwag配置文件中，可以通过以下方式控制生成的客户端基础URL：

{
  "runtime": "Net80",
  "documentGenerator": {
    "aspNetCoreToOpenApi": {
      "output": "swagger.json"
    }
  },
  "codeGenerators": {
    "openApiToCSharpClient": {
      "baseUrl": "{your-custom-base-url}",
      "generateClientInterfaces": true
    }
  }
}

最佳实践建议

1. 一致性：确保所有API路径使用统一的前缀策略
2. 测试验证：修改路径后，务必验证生成的客户端代码和文档
3. 环境隔离：为不同环境维护不同的NSwag配置文件
4. 版本控制：考虑API版本前缀的处理方式

通过这种处理方式，我们可以灵活地控制API路径在不同环境下的表现形式，同时确保生成的客户端代码能够正确工作。