.NET Core中使用Swagger实现API文档与测试

1. 为什么我们需要Swagger？

在.NET Core项目中，Swagger已经成为API文档和测试的事实标准。作为一个长期使用.NET Core开发API的开发者，我可以明确地说：没有Swagger的日子就像在黑暗中摸索前进。它不仅仅是一个文档工具，更是前后端协作的桥梁。

Swagger的核心价值在于：

• 自动生成API文档，保持文档与代码同步
• 提供交互式API测试界面，省去Postman等工具频繁切换
• 支持多种语言客户端代码生成
• 直观展示API参数、返回值、状态码等关键信息

注意：虽然Swagger非常方便，但在生产环境一定要做好访问控制，避免未授权访问漏洞。我们会在第4节详细讨论安全问题。

2. 基础环境配置

2.1 创建.NET Core Web API项目

首先确保你已经安装了最新版的Visual Studio 2022（或者使用.NET CLI）。创建项目时选择"ASP.NET Core Web API"模板，注意勾选"启用OpenAPI支持"选项：

bash复制dotnet new webapi -n MyApiProject --use-controllers --openapi true

这个命令会创建一个基础Web API项目，并自动添加Swagger相关的NuGet包引用。

2.2 添加必要的NuGet包

如果你的项目没有自动添加Swagger包，或者你需要更高级的功能，可以手动添加以下包：

bash复制dotnet add package Swashbuckle.AspNetCore
dotnet add package Swashbuckle.AspNetCore.Annotations
dotnet add package Swashbuckle.AspNetCore.SwaggerUI

这三个包分别提供了：

• 核心Swagger功能
• 增强的注解支持
• Swagger UI界面

3. 基础Swagger配置

3.1 配置Startup/Program类

在.NET 6+中，我们使用最小API模式配置Swagger。打开Program.cs文件，添加以下代码：

csharp复制var builder = WebApplication.CreateBuilder(args);

// 添加Swagger服务
builder.Services.AddSwaggerGen(c => {
    c.SwaggerDoc("v1", new OpenApiInfo { 
        Title = "My API", 
        Version = "v1",
        Description = "API文档示例",
        Contact = new OpenApiContact {
            Name = "开发者",
            Email = "dev@example.com"
        }
    });
    
    // 启用XML注释
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

var app = builder.Build();

// 开发环境下启用Swagger中间件
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c => {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

app.Run();

3.2 添加控制器和Action注释

要让Swagger显示完整的API文档，我们需要为控制器和Action添加注释：

csharp复制/// <summary>
/// 用户管理API
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    /// <summary>
    /// 获取所有用户
    /// </summary>
    /// <returns>用户列表</returns>
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok(new[] { "User1", "User2" });
    }
    
    /// <summary>
    /// 根据ID获取用户
    /// </summary>
    /// <param name="id">用户ID</param>
    /// <returns>用户信息</returns>
    [HttpGet("{id}")]
    public IActionResult GetById(int id)
    {
        return Ok($"User{id}");
    }
}

3.3 启用XML文档生成

为了让Swagger能够读取这些注释，需要在项目文件中启用XML文档生成：

xml复制<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

4. 高级配置与安全

4.1 添加JWT认证支持

在实际项目中，API通常需要认证。我们可以配置Swagger支持JWT Bearer Token：

csharp复制builder.Services.AddSwaggerGen(c => {
    // ...其他配置
    
    // 添加安全定义
    c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme {
        Description = "JWT Authorization header using the Bearer scheme.",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer"
    });
    
    c.AddSecurityRequirement(new OpenApiSecurityRequirement {
        {
            new OpenApiSecurityScheme {
                Reference = new OpenApiReference {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] {}
        }
    });
});

4.2 生产环境安全配置

Swagger UI在生产环境应该受到保护。以下是几种常见的安全措施：

1. 基本认证：

csharp复制app.UseSwaggerUI(c => {
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.RoutePrefix = "api-docs"; // 自定义路径
    
    // 添加基本认证中间件
    app.Use(async (context, next) => {
        if (context.Request.Path.StartsWithSegments("/api-docs")) {
            string authHeader = context.Request.Headers["Authorization"];
            if (authHeader != null && authHeader.StartsWith("Basic ")) {
                // 验证逻辑...
            } else {
                context.Response.Headers["WWW-Authenticate"] = "Basic";
                context.Response.StatusCode = 401;
                return;
            }
        }
        await next();
    });
});

2. IP白名单限制：

csharp复制app.UseWhen(context => context.Request.Path.StartsWithSegments("/swagger"),
    appBuilder => {
        appBuilder.Use(async (context, next) => {
            var remoteIp = context.Connection.RemoteIpAddress;
            if (!IsIpAllowed(remoteIp)) {
                context.Response.StatusCode = 403;
                return;
            }
            await next();
        });
    });

3. 环境变量控制：

csharp复制if (app.Environment.IsDevelopment() || 
    Configuration.GetValue<bool>("EnableSwaggerInProduction"))
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

5. 高级功能与自定义

5.1 添加枚举描述

让Swagger显示枚举值的描述：

csharp复制public enum UserRole {
    /// <summary>
    /// 管理员
    /// </summary>
    Admin,
    
    /// <summary>
    /// 普通用户
    /// </summary>
    User
}

// 在Swagger配置中
builder.Services.AddSwaggerGen(c => {
    c.DescribeAllEnumsAsStrings();
});

5.2 自定义OperationId

默认情况下，Swagger会生成基于方法名的OperationId。我们可以自定义：

csharp复制[HttpGet("{id}")]
[SwaggerOperation(
    OperationId = "GetUserById",
    Summary = "根据ID获取用户",
    Description = "通过用户唯一标识获取用户详细信息"
)]
public IActionResult GetById(int id)
{
    // ...
}

5.3 添加请求/响应示例

csharp复制[SwaggerRequestExample(typeof(User), typeof(UserRequestExample))]
[SwaggerResponseExample(200, typeof(UserResponseExample))]
public IActionResult GetById(int id)
{
    // ...
}

public class UserRequestExample : IExamplesProvider<User>
{
    public User GetExamples()
    {
        return new User { Id = 1, Name = "示例用户" };
    }
}

6. 常见问题与解决方案

6.1 Swagger UI无法加载

问题现象：访问/swagger端点时页面空白或报错。

排查步骤：

1. 检查控制台是否有错误输出
2. 确认是否调用了app.UseSwagger()和app.UseSwaggerUI()
3. 检查SwaggerEndpoint的路径是否正确
4. 查看浏览器开发者工具中的网络请求，确认swagger.json是否成功加载

6.2 XML注释不显示

解决方案：

1. 确认项目属性中启用了XML文档生成
2. 检查XML文件路径是否正确
3. 确保注释使用标准的///语法
4. 清理并重新生成解决方案

6.3 复杂类型显示不正确

对于复杂类型，Swagger可能无法正确推断架构。解决方法：

csharp复制builder.Services.AddSwaggerGen(c => {
    c.UseOneOfForPolymorphism();
    c.SelectDiscriminatorNameUsing(baseType => "$type");
    c.SelectDiscriminatorValueUsing(subType => subType.Name);
});

7. 性能优化建议

1. 缓存Swagger文档：

csharp复制builder.Services.AddSwaggerGen(c => {
    c.CustomSchemaIds(type => type.FullName); // 避免类型冲突
    c.IgnoreObsoleteProperties(); // 忽略过时属性
});

2. 按需加载：

csharp复制app.UseSwagger(c => {
    c.RouteTemplate = "swagger/{documentName}/swagger.json";
    c.PreSerializeFilters.Add((swaggerDoc, httpReq) => {
        // 根据请求动态修改文档
    });
});

3. 减少不必要的注释：

• 只包含必要的XML注释
• 避免过长的描述
• 使用[Obsolete]标记已弃用的API

8. 集成测试与自动化

8.1 使用Swagger进行API测试

Swagger UI不仅用于文档，还可以作为测试工具。我们可以：

1. 为API添加测试数据示例
2. 配置预设的Authorization头
3. 保存常用的测试用例

8.2 生成TypeScript客户端

bash复制npx swagger-typescript-api -p https://localhost:5001/swagger/v1/swagger.json -o ./src/api -n apiClient.ts

8.3 集成到CI/CD流程

在持续集成中，我们可以：

1. 验证Swagger文档是否符合规范
2. 生成客户端代码
3. 发布文档到内部Wiki

yaml复制# Azure Pipeline示例
- task: NodeTool@0
  inputs:
    versionSpec: '14.x'
    
- script: |
    npm install -g swagger-cli
    swagger-cli validate ./swagger/v1/swagger.json
  displayName: '验证Swagger文档'

9. 替代方案与比较

虽然Swagger是.NET Core中最流行的API文档工具，但也有其他选择：

我个人在大多数项目中仍然推荐Swagger，因为：

1. 社区支持最好
2. 与.NET Core集成最紧密
3. 功能全面且稳定

10. 实际项目中的经验分享

在多个生产项目中配置Swagger后，我总结了以下经验：

1. 版本控制很重要：每个API版本应该有独立的Swagger文档端点

csharp复制c.SwaggerDoc("v1", ...);
c.SwaggerDoc("v2", ...);

2. 组织API分组：大型项目应该按功能模块分组API

csharp复制c.DocInclusionPredicate((docName, apiDesc) => {
    if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo)) return false;
    return methodInfo.DeclaringType.GetCustomAttributes(true)
        .OfType<ApiExplorerSettingsAttribute>()
        .Any(attr => attr.GroupName == docName);
});

3. 处理泛型类型：Swagger对泛型的支持有限，需要特殊处理

csharp复制c.CustomSchemaIds(type => type.ToString());

4. 多语言支持：可以通过资源文件实现文档的多语言化

csharp复制c.OperationFilter<LocalizationOperationFilter>();

5. 性能敏感API：对于高频API，考虑禁用Swagger以减少开销

csharp复制[ApiExplorerSettings(IgnoreApi = true)]
public IActionResult HighPerformanceApi() { ... }

最后，记住Swagger只是工具，真正的价值在于保持API设计的清晰和一致。好的API设计会让Swagger文档自然变得有用，而不是反过来。