Swashbuckle for C# (.NET): 完整指南及示例

什么是 Swashbuckle 以及为什么需要它？

\n\n

Swashbuckle 是一个强大的 .NET 平台库，它基于 OpenAPI 标准（以前称为 Swagger）自动为您的 Web API 生成交互式文档。它直接集成到 ASP.NET Core 应用程序中，使开发人员、测试人员和 API 使用者能够轻松理解并与您的端点进行交互。

\n\n

为什么需要它？

\n

\n
• 文档自动化： 您无需手动编写和维护文档。Swashbuckle 会分析您的控制器、模型和属性，实时创建最新的文档。
\n
• 交互式界面 (Swagger UI)： 该库提供了一个 Web 界面，您可以在其中查看所有端点、它们的参数、数据模型，甚至可以直接从浏览器执行测试请求。
\n
• 标准化： OpenAPI 是行业标准。生成的文档可用于在不同语言（JavaScript、Python、Java 等）中自动生成客户端 SDK。
\n
• 简化测试和调试： 开发人员和 QA 工程师无需使用 Postman 等第三方工具即可快速测试 API（尽管 Postman 也可以导入 OpenAPI 规范）。
\n

\n\n

Swashbuckle 由两个主要组件组成：Swashbuckle.AspNetCore.Swagger（生成 OpenAPI JSON 规范）和 Swashbuckle.AspNetCore.SwaggerUI（显示交互式界面）。

\n\n

安装

\n\n

Swashbuckle 通过 NuGet 包管理器安装。您可以使用包管理器控制台、.NET CLI 或 Visual Studio 界面。

\n\n

通过 .NET CLI（推荐）

\n

dotnet add package Swashbuckle.AspNetCore\n

\n\n

通过 Visual Studio 中的包管理器控制台

\n

Install-Package Swashbuckle.AspNetCore\n

\n\n

此命令将安装主包，其中包含所有必要的组件：Swagger、SwaggerUI 和 Swashbuckle.Core。

\n\n

快速入门及代码示例

\n\n

让我们看一下为 ASP.NET Core Web API 配置 Swashbuckle 的最小设置。

\n\n

1. 创建一个新的 Web API 项目

\n

dotnet new webapi -n MySwaggerApi\ncd MySwaggerApi\n

\n\n

2. 添加 Swashbuckle

\n

dotnet add package Swashbuckle.AspNetCore\n

\n\n

3. 配置 Program.cs

\n

打开 Program.cs 文件并添加以下行：

\n\n

using Microsoft.OpenApi.Models;\n\nvar builder = WebApplication.CreateBuilder(args);\n\n// 添加 Swagger 服务\nbuilder.Services.AddEndpointsApiExplorer();\nbuilder.Services.AddSwaggerGen(c =>\n{\n    c.SwaggerDoc("v1", new OpenApiInfo\n    {\n        Title = "My Awesome API",\n        Version = "v1",\n        Description = "An example API to demonstrate Swashbuckle"\n    });\n});\n\nvar app = builder.Build();\n\n// 启用 Swagger 中间件\nif (app.Environment.IsDevelopment())\n{\n    app.UseSwagger();\n    app.UseSwaggerUI();\n}\n\napp.UseHttpsRedirection();\n\n// 简单端点示例\nvar summaries = new[]\n{\n    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"\n};\n\napp.MapGet("/weatherforecast", () =>\n{\n    var forecast = Enumerable.Range(1, 5).Select(index =>\n        new WeatherForecast\n        (\n            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),\n            Random.Shared.Next(-20, 55),\n            summaries[Random.Shared.Next(summaries.Length)]\n        ))\n        .ToArray();\n    return forecast;\n})\n.WithName("GetWeatherForecast");\n\napp.Run();\n\nrecord WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)\n{\n    public int TemperatureF => 32 + (int)(TemperatureC / 0.55