ASP.NET API 版本控制中的Swagger配置详解

概述

在ASP.NET Core Web API开发中，API版本控制和API文档生成是两个非常重要的功能。本文将以一个实际示例为基础，深入讲解如何在使用ASP.NET API版本控制时，为每个API版本自动生成对应的Swagger文档。

核心组件介绍

IApiVersionDescriptionProvider

这是一个关键接口，它提供了当前应用程序中所有已注册API版本的描述信息。通过这个接口，我们可以获取每个API版本的详细信息，包括版本号、是否已弃用等。

SwaggerGenOptions

SwaggerGen是Swashbuckle.AspNetCore库中的核心类，用于配置Swagger文档生成的各种选项。我们可以通过配置这个选项来定制生成的OpenAPI文档。

实现原理

配置类结构

示例中的ConfigureSwaggerOptions类实现了IConfigureOptions<SwaggerGenOptions>接口，这意味着它可以在应用程序启动时对Swagger生成选项进行配置。

主要功能

1. 多版本文档生成：为每个发现的API版本创建一个独立的Swagger文档
2. 版本信息定制：根据API版本的不同状态（如已弃用）显示不同的描述信息
3. 日落策略支持：展示API版本的淘汰计划信息

代码详解

构造函数

public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) => this.provider = provider;

这里注入了IApiVersionDescriptionProvider服务，它提供了所有API版本的描述信息。

Configure方法

public void Configure(SwaggerGenOptions options)
{
    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description));
    }
}

这个方法遍历所有API版本描述，为每个版本创建一个Swagger文档。文档的基本信息由CreateInfoForApiVersion方法生成。

创建API版本信息

private static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description)
{
    var text = new StringBuilder("示例应用程序，包含OpenAPI、Swashbuckle和API版本控制。");
    var info = new OpenApiInfo()
    {
        Title = "示例API",
        Version = description.ApiVersion.ToString(),
        Contact = new OpenApiContact() { Name = "Bill Mei", Email = "bill.mei@somewhere.com" },
        License = new OpenApiLicense() { Name = "MIT", Url = new Uri("https://opensource.org/licenses/MIT") }
    };
    
    // 处理已弃用版本
    if (description.IsDeprecated)
    {
        text.Append(" 此API版本已被弃用。");
    }
    
    // 处理日落策略
    if (description.SunsetPolicy is SunsetPolicy policy)
    {
        // 添加日落日期信息
        if (policy.Date is DateTimeOffset when)
        {
            text.Append(" API将在")
                .Append(when.Date.ToShortDateString())
                .Append('停止服务。');
        }
        
        // 添加相关链接
        if (policy.HasLinks)
        {
            text.AppendLine();
            for (var i = 0; i < policy.Links.Count; i++)
            {
                var link = policy.Links[i];
                if (link.Type == "text/html")
                {
                    text.AppendLine();
                    if (link.Title.HasValue)
                    {
                        text.Append(link.Title.Value).Append(": ");
                    }
                    text.Append(link.LinkTarget.OriginalString);
                }
            }
        }
    }
    
    info.Description = text.ToString();
    return info;
}

这个方法为每个API版本创建详细的OpenAPI信息，包括：

• 基本API信息（标题、版本号）
• 联系人信息
• 许可证信息
• 针对已弃用版本的特殊标记
• 日落策略的详细信息

实际应用

要在项目中使用这个配置类，需要在Startup或Program类中进行如下配置：

// 注册API版本服务
services.AddApiVersioning()
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";
        options.SubstituteApiVersionInUrl = true;
    });

// 注册Swagger生成器
services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
services.AddSwaggerGen();

最佳实践

1. 版本命名规范：建议使用一致的版本命名方案，如"v1"、"v2"等
2. 弃用策略：对于已弃用的API版本，应在文档中明确标记
3. 日落策略：为即将淘汰的API版本提供清晰的淘汰时间表和迁移指南
4. 文档一致性：确保所有版本的API文档风格一致

总结

通过本文介绍的配置方法，我们可以轻松地为每个API版本生成详细的Swagger文档，包括版本状态、淘汰计划等重要信息。这不仅提高了API的可发现性，也为API使用者提供了清晰的版本演进路线图。

在实际项目中，这种配置方式可以大大简化API版本管理和文档维护的工作量，特别是在大型项目或长期维护的项目中，其价值更为明显。