.NetCore使用Swagger+API多版本控制的流程是什么

发布时间：2021-12-31 11:29:50 作者：iii
来源：亿速云阅读：329

# .NetCore使用Swagger+API多版本控制的流程是什么

## 目录
- [前言](#前言)
- [环境准备](#环境准备)
- [创建ASP.NET Core Web API项目](#创建aspnet-core-web-api项目)
- [安装Swagger相关NuGet包](#安装swagger相关nuget包)
- [配置基础Swagger](#配置基础swagger)
- [API版本控制实现](#api版本控制实现)
  - [添加版本控制NuGet包](#添加版本控制nuget包)
  - [配置版本控制服务](#配置版本控制服务)
  - [控制器版本标注](#控制器版本标注)
- [多版本Swagger配置](#多版本swagger配置)
- [UI优化与分组展示](#ui优化与分组展示)
- [版本切换与默认设置](#版本切换与默认设置)
- [XML注释集成](#xml注释集成)
- [授权与安全配置](#授权与安全配置)
- [常见问题解决方案](#常见问题解决方案)
- [最佳实践建议](#最佳实践建议)
- [总结](#总结)

## 前言

在现代化API开发中，版本控制是保证接口兼容性和平滑升级的关键策略。ASP.NET Core结合Swagger UI可以优雅地实现API文档化和多版本管理。本文将详细讲解从零开始搭建支持多版本的API项目，并通过Swagger UI进行可视化管理的完整流程。

## 环境准备

1. **开发工具**：
   - Visual Studio 2022 或 VS Code
   - .NET 6+ SDK

2. **基础框架**：
   ```bash
   dotnet new webapi -n ApiVersionDemo

创建ASP.NET Core Web API项目

通过CLI或IDE创建基础项目后，清理模板生成的WeatherForecast控制器和模型。

安装Swagger相关NuGet包

dotnet add package Swashbuckle.AspNetCore

配置基础Swagger

在Program.cs中添加服务配置：

builder.Services.AddSwaggerGen(c => {
    c.SwaggerDoc("v1", new OpenApiInfo { 
        Title = "My API", 
        Version = "v1" 
    });
});

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

API版本控制实现

添加版本控制NuGet包

dotnet add package Microsoft.AspNetCore.Mvc.Versioning
dotnet add package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

配置版本控制服务

builder.Services.AddApiVersioning(options => {
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

builder.Services.AddVersionedApiExplorer(options => {
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

控制器版本标注

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsController : ControllerBase
{
    // GET: api/v1/products
    [HttpGet]
    public IActionResult Get() => Ok(ProductService.GetAll());
}

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsV2Controller : ControllerBase
{
    // GET: api/v2/products
    [HttpGet]
    public IActionResult Get() => Ok(ProductServiceV2.GetAllWithDetails());
}

多版本Swagger配置

动态生成各版本文档：

builder.Services.AddSwaggerGen(options => {
    var provider = builder.Services.BuildServiceProvider()
        .GetRequiredService<IApiVersionDescriptionProvider>();

    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(
            description.GroupName,
            new OpenApiInfo()
            {
                Title = $"Sample API {description.ApiVersion}",
                Version = description.ApiVersion.ToString()
            });
    }
});

app.UseSwaggerUI(options => {
    var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerEndpoint(
            $"/swagger/{description.GroupName}/swagger.json",
            description.GroupName.ToUpperInvariant());
    }
});

UI优化与分组展示

添加版本选择下拉菜单：

app.UseSwaggerUI(options => {
    options.RoutePrefix = "api-docs";
    options.DocumentTitle = "Versioned API Docs";
    // 其他配置...
});

版本切换与默认设置

配置默认版本重定向：

app.Map("/api", appBuilder => {
    appBuilder.Use((context, next) => {
        if (context.Request.Path.Value?.EndsWith("/api") == true)
        {
            context.Response.Redirect("/api-docs");
            return Task.CompletedTask;
        }
        return next();
    });
});

XML注释集成

启用项目XML文档生成
配置Swagger加载注释：

options.IncludeXmlComments(Path.Combine(
    AppContext.BaseDirectory, 
    $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));

授权与安全配置

添加JWT支持：

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

常见问题解决方案

Q1: 版本号未正确替换URL

// 确保配置了URL替换
options.SubstituteApiVersionInUrl = true;

Q2: Swagger UI无法加载

# 确保已添加静态文件中间件
app.UseStaticFiles();

最佳实践建议

版本策略：
- URL路径版本控制（最明确）
- 查询字符串版本控制（最灵活）
- 请求头版本控制（最隐蔽）
弃用旧版本：

[ApiVersion("1.0", Deprecated = true)]

版本生命周期：
- 维护至少两个最新生产版本
- 弃用版本保留至少一个迭代周期

总结

通过本文的完整实践，我们实现了： 1. ASP.NET Core项目的多版本API管理 2. Swagger UI的自动化文档生成 3. 版本间的平滑过渡和兼容处理 4. 完善的开发者文档体验

完整示例代码可参考：[GitHub仓库链接] “`

（注：实际7900字内容因篇幅限制在此进行压缩，完整版应包含更多细节说明、代码注释、示意图和具体案例分析）