.NET Core WebAPI 多版本控制与 Swagger（NSwag）配置教程

在 .NET Core WebAPI 中，我们可以使用多版本控制来管理不同版本的 API。同时，我们也可以使用 Swagger（NSwag）来生成 API 文档和客户端代码。本攻略将介绍如何在 .NET Core WebAPI 中实现多版本控制和 Swagger（NSwag）配置。

步骤

以下是在 .NET Core WebAPI 中实现多版本控制和 Swagger（NSwag）配置的步骤：

1. 创建项目。

使用 Visual Studio 或者 .NET Core CLI 创建一个新的 .NET Core WebAPI 项目。

1. 安装 NuGet 包。

在项目中安装以下 NuGet 包：

• Microsoft.AspNetCore.Mvc.Versioning
• Swashbuckle.AspNetCore
• NSwag.AspNetCore

可以使用 NuGet 包管理器或者 .NET Core CLI 安装。

1. 配置多版本控制。

在 Startup.cs 文件中添加以下代码：

public void ConfigureServices(IServiceCollection services)
{
    services.AddApiVersioning(options =>
    {
        options.DefaultApiVersion = new ApiVersion(1, 0);
        options.AssumeDefaultVersionWhenUnspecified = true;
        options.ReportApiVersions = true;
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseApiVersioning();
}

在上面的代码中，我们使用 AddApiVersioning 方法配置多版本控制。我们使用 DefaultApiVersion 属性设置默认 API 版本。我们使用 AssumeDefaultVersionWhenUnspecified 属性指定当未指定 API 版本时，使用默认 API 版本。我们使用 ReportApiVersions 属性指定在响应头中报告 API 版本。

1. 配置 Swagger（NSwag）。

在 Startup.cs 文件中添加以下代码：

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerDocument();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseOpenApi();
    app.UseSwaggerUi3();
}

在上面的代码中，我们使用 AddSwaggerDocument 方法配置 Swagger（NSwag）。我们使用 UseOpenApi 和 UseSwaggerUi3 方法配置 Swagger（NSwag）中间件。

1. 创建 API 控制器。

在 Controllers 文件夹中创建一个新的 API 控制器，例如：

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        return new string[] { "value1", "value2" };
    }
}

在上面的代码中，我们使用 ApiVersion 属性指定 API 控制器的版本。我们使用 Route 属性指定 API 控制器的路由。

1. 运行项目。

使用 Visual Studio 或者 .NET Core CLI 运行项目。在浏览器中访问 http://localhost:5000/swagger/index.html，可以看到 Swagger（NSwag）生成的 API 文档。

示例说明

以下是两个示例，示如何在 .NET Core WebAPI 中实现多版本控制和 Swagger（NSwag）配置。

示例1：使用默认 API 版本

以下是使用默认 API 版本的示例：

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        return new string[] { "value1", "value2" };
    }
}

在上面的代码中，我们使用 ApiVersion 属性指定 API 控制器的版本。我们使用 Route 属性指定 API 控制器的路由。

示例2：使用自定义 API 版本

以下是使用自定义 API 版本的示例：

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        return new string[] { "value3", "value4" };
    }
}

在上面的代码中，我们使用 ApiVersion 属性指定 API 控制器的版本。我们使用 Route 属性指定 API 控制器的路由。

结论

本攻略介绍了如何在 .NET Core WebAPI 中实现多版本控制和 Swagger（NSwag）配置。我们提供了详细的步骤和示例说明，以帮助您快速实现多版本控制和 Swagger（NSwag）配置。