Swagger/OpenAPI 用于 C# (.NET)：API 生成与文档

Swagger/OpenAPI 生成用于 C# (.NET)

Swagger（现在正式称为 OpenAPI）是一个用于设计、构建、记录和使用 RESTful API 的强大工具。在 .NET 生态系统中，生成 OpenAPI 规范和交互式文档已成为现代 Web 服务开发中不可或缺的一部分。在本文中，我们将详细介绍如何使用 Swashbuckle.AspNetCore 库在 C# (.NET) 应用程序中配置自动生成 Swagger/OpenAPI。

Swagger 不仅可以自动创建可读的文档，还提供了一个交互式界面（Swagger UI），用于直接在浏览器中测试端点。这大大加快了团队之间的开发和集成速度。

在 .NET 中安装和配置 Swashbuckle

首先，我们需要安装 Swashbuckle.AspNetCore 包。这是主要的包，包含 Swagger 生成器、Swagger UI 以及与 ASP.NET Core 的集成。

通过 NuGet 包管理器控制台安装：

Install-Package Swashbuckle.AspNetCore

或者通过 .NET CLI：

dotnet add package Swashbuckle.AspNetCore

安装包后，需要在 Program.cs（或旧版本的 Startup.cs）文件中配置服务。以下是 .NET 8 及更高版本的最小配置：

var builder = WebApplication.CreateBuilder(args);

// 添加 Swagger 服务builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo    {        Title = "My API",        Version = "v1",        Description = "带有 Swagger 文档的 API 示例"    });});

builder.Services.AddControllers();

var app = builder.Build();

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

app.UseHttpsRedirection();app.MapControllers();

app.Run();

Swashbuckle 的主要功能

• 自动生成 OpenAPI 规范 — 该库分析您的控制器、数据模型和属性，创建 JSON/YAML 格式的规范文件。
• 交互式 Swagger UI — 一个 Web 界面，您可以在其中查看端点、发送请求并查看响应。
• 支持 XML 注释 — 如果您为控制器和模型添加 XML 文档，Swagger 会将其显示在界面中。
• 按版本分组 — 可以为不同版本的 API 创建多个版本的文档。
• 自定义 — 可以自定义外观、添加标头、身份验证方案（JWT、Basic Auth）等。

为文档添加 XML 注释

为了使您的文档信息丰富，请使用 XML 注释。首先，在项目中启用 XML 文件生成。打开 .csproj 文件并添加：

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

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

builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });        // 指定 XML 文档文件的路径    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

现在，代码中的注释将显示在 Swagger UI 中。带有注释的控制器示例：

/// <summary>