ASP.NET Core Web API 中使用 Swagger 生成 API 文档教程

前言

在现代 Web API 开发中，良好的 API 文档是项目成功的关键因素之一。本文将详细介绍如何在 ASP.NET Core Web API 项目中集成 Swagger，自动生成美观且功能强大的 API 文档。

Swagger 简介

Swagger 是一个开源工具集，可以帮助开发者设计、构建、记录和使用 RESTful API。它通过 OpenAPI 规范（原 Swagger 规范）来描述 API 结构，并提供交互式文档界面。

项目配置

1. 添加 Swagger 服务

首先需要在 Startup.cs 文件的 ConfigureServices 方法中添加 Swagger 服务：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "A simple example ASP.NET Core Web API",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = new Uri("https://twitter.com/spboyer"),
        },
        License = new OpenApiLicense
        {
            Name = "Use under LICX",
            Url = new Uri("https://example.com/license"),
        }
    });

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

这段代码做了以下几件事：

1. 配置了 API 的基本信息（版本、标题、描述等）
2. 设置了服务条款、联系人和许可证信息
3. 配置了从 XML 注释文件生成文档

2. 启用 Swagger 中间件

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

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

这里我们只在开发环境中启用 Swagger，生产环境中通常会禁用。UseSwagger 中间件生成 JSON 格式的 API 描述，UseSwaggerUI 中间件提供可视化界面。

XML 注释集成

为了从代码注释生成更详细的文档，需要：

1. 在项目属性中启用 XML 文档生成
2. 确保每个控制器和模型都有详细的注释

例如控制器方法的注释：

/// <summary>
/// 获取所有待办事项
/// </summary>
/// <remarks>
/// 示例请求:
/// 
///     GET /Todo
///     
/// </remarks>
/// <returns>待办事项列表</returns>
/// <response code="200">返回所有待办事项</response>
[HttpGet]
public async Task<ActionResult<IEnumerable<TodoItem>>> GetTodoItems()
{
    return await _context.TodoItems.ToListAsync();
}

高级配置

安全性定义

可以为需要认证的 API 添加安全性定义：

c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
    Description = "JWT Authorization header using the Bearer scheme.",
    Name = "Authorization",
    In = ParameterLocation.Header,
    Type = SecuritySchemeType.ApiKey
});

自定义操作过滤器

可以创建自定义操作过滤器来修改生成的文档：

public class SwaggerOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 自定义操作
    }
}

然后在 AddSwaggerGen 中注册：

services.AddSwaggerGen(c =>
{
    // 其他配置...
    c.OperationFilter<SwaggerOperationFilter>();
});

最佳实践

1. 环境区分：生产环境应禁用 Swagger UI
2. 版本控制：为不同 API 版本创建不同的文档
3. 详细注释：为所有公共 API 添加详细注释
4. 示例值：提供请求/响应示例
5. 错误代码：文档化所有可能的错误响应

总结

通过集成 Swagger，我们可以为 ASP.NET Core Web API 项目自动生成交互式文档，极大提高了 API 的可用性和开发效率。本文介绍了基本配置方法以及一些高级技巧，开发者可以根据项目需求进行适当调整。