ASP.NET Core 中使用 Swashbuckle 实现 API 文档自动化

什么是 Swashbuckle？

Swashbuckle 是一个流行的 .NET 库，它能自动为 ASP.NET Core Web API 生成 Swagger/OpenAPI 文档。它由三个核心组件组成：

1. Swagger 对象模型和中间件：提供 SwaggerDocument 对象的 JSON 端点
2. Swagger 生成器：直接从路由、控制器和模型构建 SwaggerDocument 对象
3. 嵌入式 Swagger UI：可视化展示 API 文档并支持交互式测试

安装 Swashbuckle

通过 NuGet 安装

在项目中安装 Swashbuckle.AspNetCore 包：

Install-Package Swashbuckle.AspNetCore -Version 6.6.2

或者使用 .NET CLI：

dotnet add package Swashbuckle.AspNetCore -v 6.6.2

基本配置

1. 添加服务

在 Program.cs 文件中添加 Swagger 服务：

builder.Services.AddSwaggerGen();

对于最小 API 项目，还需要添加：

builder.Services.AddEndpointsApiExplorer();

2. 启用中间件

在开发环境中启用 Swagger 中间件：

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

访问 Swagger UI

启动应用后，可以通过以下 URL 访问：

• Swagger JSON 文档：/swagger/v1/swagger.json
• Swagger UI 界面：/swagger

高级配置

自定义 API 信息

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "我的API",
        Version = "v1",
        Description = "这是一个示例API",
        Contact = new OpenApiContact
        {
            Name = "开发者",
            Email = "dev@example.com"
        },
        License = new OpenApiLicense
        {
            Name = "使用许可证"
        }
    });
});

启用 XML 注释

1. 在项目文件中启用 XML 文档生成：

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

2. 配置 Swagger 使用 XML 文件：

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

使用数据注解增强文档

public class TodoItem
{
    [Required]
    public string Name { get; set; }
    
    [MaxLength(500)]
    public string Description { get; set; }
}

描述响应类型

使用 [ProducesResponseType] 属性：

[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    // ...
}

自定义 UI 样式

1. 首先启用静态文件中间件：

app.UseStaticFiles();

2. 添加自定义 CSS：

app.UseSwaggerUI(c =>
{
    c.InjectStylesheet("/swagger-ui/custom.css");
});

注意事项

1. 在 IIS 或反向代理后使用时，建议使用相对路径 ./swagger/v1/swagger.json
2. 默认生成 OpenAPI 3.0 规范，如需 2.0 格式可配置：

app.UseSwagger(c => c.SerializeAsV2 = true);

最佳实践

1. 为所有公共方法和类型添加 XML 注释
2. 使用数据注解提供额外的元数据
3. 为所有 API 端点明确指定响应类型
4. 考虑为大型项目使用 API 版本控制
5. 在生产环境中限制 Swagger UI 的访问

通过以上配置，Swashbuckle 可以自动为你的 ASP.NET Core Web API 生成完整、专业的文档，大大提升 API 的可发现性和易用性。