ASP.NET Core Web API 集成 Swashbuckle 实现 Swagger UI 文档指南

前言

在现代 Web API 开发中，良好的 API 文档对于开发者体验至关重要。本文将详细介绍如何在 ASP.NET Core Web API 项目中集成 Swashbuckle 来实现 Swagger UI 文档功能，帮助开发者快速理解和使用 API。

Swagger 与 Swashbuckle 简介

Swagger 是一种用于描述 RESTful API 的规范，现已成为 OpenAPI 标准。它能够：

1. 自动生成交互式 API 文档
2. 提供 API 发现功能
3. 支持客户端 SDK 生成

Swashbuckle.AspNetCore 是 .NET 平台上的 Swagger 实现，能够无缝集成到 ASP.NET Core 项目中。

基础集成步骤

1. 添加 Swagger 中间件

首先在 Startup.cs 的 ConfigureServices 方法中添加 Swagger 生成器：

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt => 
        opt.UseInMemoryDatabase("TodoList"));
    services.AddControllers();

    // 注册 Swagger 生成器，定义一个或多个 Swagger 文档
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { 
            Title = "我的API", 
            Version = "v1" 
        });
    });
}

2. 启用中间件

在 Configure 方法中启用 Swagger 中间件：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 仅在开发环境启用 Swagger
    if (env.IsDevelopment())
    {
        app.UseSwagger();
        app.UseSwaggerUI(c => 
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "我的API V1");
        });
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

访问 Swagger UI

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

• Swagger JSON 文档：http://localhost:<port>/swagger/v1/swagger.json
• Swagger UI 界面：http://localhost:<port>/swagger

进阶配置

自定义 API 信息

可以丰富 API 文档的基本信息：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "待办事项API",
        Description = "一个简单的ASP.NET Core Web API示例",
        Contact = new OpenApiContact
        {
            Name = "开发者",
            Email = "dev@example.com"
        },
        License = new OpenApiLicense
        {
            Name = "使用许可"
        }
    });
});

启用 XML 注释

XML 注释可以显著提升文档质量，启用步骤：

1. 编辑项目文件(.csproj)，添加：

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

2. 配置 Swagger 使用 XML 文件：

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

添加控制器注释示例

/// <summary>
/// 删除特定的待办事项
/// </summary>
/// <param name="id">待办事项ID</param>
[HttpDelete("{id}")]
public IActionResult Delete(long id)
{
    // 实现代码
}

数据注解增强

使用数据注解可以进一步改善文档：

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; }

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

响应类型描述

明确描述 API 的响应类型：

/// <response code="201">返回新创建的项</response>
/// <response code="400">如果项为null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public ActionResult<TodoItem> Create(TodoItem item)
{
    // 实现代码
}

部署注意事项

在 IIS 或反向代理后部署时，建议使用相对路径：

c.SwaggerEndpoint("./swagger/v1/swagger.json", "My API V1");

结语

通过 Swashbuckle 集成 Swagger UI，我们可以为 ASP.NET Core Web API 自动生成专业、交互式的文档。这不仅提升了开发效率，也大大改善了 API 的使用体验。本文介绍的基础和进阶配置应该能满足大多数项目的需求，开发者可以根据实际情况进一步定制和扩展。