.net6+Swagger版本控制

原创

mob649e8159b30b 2023-07-20 20:37:26 ©著作权

文章标签 API 版本控制 UI 文章分类 .Net 后端开发

©著作权归作者所有：来自51CTO博客作者mob649e8159b30b的原创作品，请联系作者获取转载授权，否则将追究法律责任

.NET 6 + Swagger 版本控制实现流程

流程概述

在实现.NET 6 + Swagger版本控制时，需要完成以下步骤：

添加版本控制支持
配置Swagger文档生成器
配置Swagger UI
编写控制器和API端点
测试API端点

接下来，我们将逐一介绍每个步骤和所需的代码。

1. 添加版本控制支持

在.NET 6中，我们可以使用Microsoft.AspNetCore.Mvc.Versioning包来实现版本控制。在项目的*.csproj文件中添加以下引用：

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="4.1.1" />
</ItemGroup>

2. 配置Swagger文档生成器

使用Swashbuckle.AspNetCore包生成Swagger文档。在项目的*.csproj文件中添加以下引用：

<ItemGroup>
  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
</ItemGroup>

在Startup.cs文件中的ConfigureServices方法中，添加以下代码来注册Swagger生成器和配置版本控制：

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.SwaggerGen;

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    
    services.AddApiVersioning(options =>
    {
        options.DefaultApiVersion = new ApiVersion(1, 0);
        options.AssumeDefaultVersionWhenUnspecified = true;
        options.ReportApiVersions = true;
    });
    
    services.AddVersionedApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";
        options.SubstituteApiVersionInUrl = true;
    });
    
    services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
    services.AddSwaggerGen();
}

请注意上述代码中的ConfigureSwaggerOptions，我们需要在后续步骤中实现该类。

3. 配置Swagger UI

在Startup.cs文件中的Configure方法中，添加以下代码以启用Swagger UI：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc.ApiExplorer;

public void Configure(IApplicationBuilder app, IApiVersionDescriptionProvider provider)
{
    // ... 其他中间件配置
    
    app.UseSwagger();
    
    app.UseSwaggerUI(options =>
    {
        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
        }
    });
    
    // ... 其他中间件配置
}

4. 编写控制器和API端点

现在，我们可以开始编写控制器和API端点，并使用版本控制的注解来标识它们。以下是一个示例：

using Microsoft.AspNetCore.Mvc;

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/values")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new string[] { "value1", "value2" });
    }
}

在上述示例中，我们使用了[ApiVersion]注解来指定该控制器和API端点的版本。可以根据需要在同一控制器中定义多个版本的API。