Swagger/OpenAPI 生成用于 C# (.NET)：Swashbuckle 和 NSwag

Swagger/OpenAPI 生成用于 C# (.NET)：Swashbuckle 和 NSwag

记录 REST API 是现代 C# (.NET) 开发中不可或缺的一部分。OpenAPI 规范（以前称为 Swagger）允许以统一的、机器可读的格式（JSON/YAML）描述端点、数据模型、参数和响应。在 .NET Core / .NET 5+ 生态系统中，有两个主要工具用于自动生成 OpenAPI 规范：Swashbuckle.AspNetCore 和 NSwag。这两个工具都集成到 ASP.NET Core 中，分析您的代码并创建交互式文档（Swagger UI）。

Swashbuckle.AspNetCore：经典选择

Swashbuckle 是 .NET 中最流行的 Swagger/OpenAPI 生成包。它根据控制器、路由属性和模型注释自动构建规范。支持 OpenAPI 3.0 和 Swagger 2.0。

安装和基本配置

dotnet add package Swashbuckle.AspNetCore

在 Program.cs 文件（或旧版本的 Startup.cs）中，添加服务和中间件：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo    {        Title = "我的 API",        Version = "v1",        Description = "用于教育网站的示例 API"    });});

var app = builder.Build();

if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(c =>    {        c.SwaggerEndpoint("/swagger/v1/swagger.json", "我的 API v1");    });}

app.MapControllers();app.Run();

启动后，访问 /swagger 地址——将打开交互式 UI，您可以直接在浏览器中测试端点。

添加 XML 注释

为了使 XML 注释中的描述进入文档，请在 .csproj 中启用 XML 生成：

<PropertyGroup>  <GenerateDocumentationFile>true</GenerateDocumentationFile></PropertyGroup>

然后在 AddSwaggerGen 中指定 XML 文件的路径：

builder.Services.AddSwaggerGen(c =>{    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

现在，代码中的注释将显示在 Swagger UI 中。

带有注释的控制器示例

[ApiController][Route("api/[controller]")]public class ProductsController : ControllerBase{    /// <summary>    /// 获取所有产品列表    /// </summary>    [HttpGet]    public ActionResult<IEnumerable<Product>> GetAll()    {        return Ok(new List<Product>());    }

    /// <summary>    /// 根据 ID 获取产品    /// </summary>    /// <param name="id">产品标识符</param>    [HttpGet("{id}")]    public ActionResult<Product> GetById(int id)    {        return Ok(new Product { Id = id, Name = "示例" });    }}

NSwag：带有客户端生成的通用工具

NSwag 是一个更强大的替代方案。除了生成文档外，它还可以为 API 创建 C# 客户端、TypeScript 客户端，以及基于外部 OpenAPI 规范生成代码。

安装和配置

dotnet add package NSwag.AspNetCore

在 Program.cs 中进行配置：

builder.Services.AddOpenApiDocument(config =>{    config.Title = "我的 API (NSwag)";    config.Version = "v1";    config.Description = "使用 NSwag 生成的 API";});

// ...