在 .NET 5 Web API 中设置 Swagger 和 API 版本控制

如果您正在开发任何 API，那么拥有良好的文档和适当的版本控制绝对至关重要。在这篇博文中，我将展示如何在 .NET 5 Web API 中设置 API 版本控制和 Swagger。出于演示目的，我使用 Visual Studio 创建了一个新的 .NET 5 API 项目。源代码可以在这里找到：github.com/Ngineer101/swagger-api-versioning-dotnet-core。

---

什么是Swagger ？

Swagger 是一种接口描述语言，与其他开源工具结合使用，用于构建和记录 RESTful API。

---

第1步

要开始设置 Swagger 和 API 版本控制，请安装所需的 NuGet 包：

• 对于 API 版本控制：

  • https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

• 对于招摇：

  • https://www.nuget.org/packages/Swashbuckle.AspNetCore

第2步

要设置 API 版本控制，请ConfigureServices在类的方法中添加以下代码Startup.cs：

    services.AddControllers();

    // Add the code below
    services.AddApiVersioning(options =>
    {
        options.ReportApiVersions = true;
        options.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0);
    });

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

上述代码将版本控制服务添加到应用程序容器，并将默认 API 版本设置为1.0.

第 3 步

3.1.

在配置 Swagger 之前，为您的项目启用 XML 文档。您可以通过导航到项目属性来执行此操作：

解决方案资源管理器>右键单击​​项目>属性>构建选项卡

单击复选框以启用 XML 文档并在“抑制警告”文本框中添加额外的警告代码 1591，如屏幕截图所示。抑制警告代码将阻止编译器显示应用程序中所有未记录的类型和属性的警告。

3.2.

要设置 Swagger，请创建一个名为SwaggerConfigureOptions.cs. 将以下代码添加到类中：

    public class SwaggerConfigureOptions : IConfigureOptions<SwaggerGenOptions>
    {
        private readonly IApiVersionDescriptionProvider _provider;

        public SwaggerConfigureOptions(IApiVersionDescriptionProvider provider) => _provider = provider;

        public void Configure(SwaggerGenOptions options)
        {
            foreach (var desc in _provider.ApiVersionDescriptions)
            {
                options.SwaggerDoc(desc.GroupName, new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Title = "My Test API",
                    Version = desc.ApiVersion.ToString(),
                });
            }
        }
    }

此代码将确保为每个 API 版本生成唯一的 Swagger 文档。

3.3.

要将 Swagger 服务添加到容器中，请ConfigureServices在类中的方法中添加以下代码Startup.cs：

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFile);

    services.AddTransient<IConfigureOptions<SwaggerGenOptions>, SwaggerConfigureOptions>();
    services.AddSwaggerGen(options =>
    {
        options.IncludeXmlComments(xmlFilePath);
    });

3.4.

Configure要在 HTTP 请求管道中使用 Swagger，请在类中的方法中添加以下代码Startup.cs：

    app.UseSwagger(options =>
    {
        options.PreSerializeFilters.Add((swagger, req) =>
        {
            swagger.Servers = new List<OpenApiServer>() { new OpenApiServer() { Url = $"https://{req.Host}" } };
        });
    });

    app.UseSwaggerUI(options =>
    {
        foreach (var desc in apiVersionDescriptionProvider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"../swagger/{desc.GroupName}/swagger.json", desc.ApiVersion.ToString());
            options.DefaultModelsExpandDepth(-1);
            options.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None);
        }
    });

设置 API 版本控制和 Swagger 后，您可以[ApiVersion]在控制器中添加属性并使用 XML 注释记录 API 端点。

示例控制器如下所示：

    [ApiVersion("1.0")]
    [Route("api/v{version:apiVersion}/message")]
    [ApiController]
    public class MessageController : ControllerBase
    {
        /// <summary>
        /// Gets message by ID
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        [HttpGet("{id}")]
        public ActionResult<List<Message>> Get(int id)
        {
            return Ok(new Message
            {
                Id = id,
                Text = "Hello world"
            });
        }
    }

如果您运行 API 项目并导航到 URL ( https://localhost:5001/swagger)，您将看到记录在案的 API，如屏幕截图所示：

如果您对源代码感兴趣，请在此处查看存储库。

https://nwb.one/blog/swagger-api-versioning-dotnet-core