向ASP.NET Core Swagger文档添加新的API版本

ybzsozfc  于 2023-03-23  发布在  .NET
关注(0)|答案(1)|浏览(140)

我有一个API和关联的Swagger文档

我有一个ASP.NET Core 7 API项目,连接起来生成Swagger文档。相关的初始化代码,在Program.cs中,看起来像这样:

// Initialization
var builder = WebApplication.CreateBuilder(args);
var services = builder.Services;
var configuration = builder.Configuration;

// Configure Swagger
// See: https://aka.ms/aspnetcore/swashbuckle
services.AddEndpointsApiExplorer();
services.AddSwaggerGen(options => {
    // Basic API info
    options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo {
        Title = "My example API",
        Version = "v1",
        Description = "REST API for interacting with my example functions and data",
        TermsOfService = new Uri("https://example.com/ApiTermsOfUse")
    });

    // Wire up the XML comments, which have been generated in .xml files in more than one project
    foreach (var filePath in System.IO.Directory.GetFiles(Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location)!), "*.xml")) {
        try {
            options.IncludeXmlComments(filePath);
        }

        catch (Exception ex) when(ex.OkToCatch()) {
            // <Ignore the exception>
        }
    }
});

我的API包含几个控制器(PatientAppControllerProviderControllerServerInfoController),每个控制器在Swagger显示中生成一个单独的部分。

现在我想弃用API的PatientApp部分的1.0版本,并添加相同API端点的2.0版本。

因此,我将PatientAppController复制到一个新的PatientAppV2Controller中,并向class定义中添加了一些属性:

PatientAppController

[ApiController]
    [Route("v{version:apiVersion}/[controller]/[action]")] // Rout: https://example.com/v1/PatientApp/SomeAction
    [ApiVersion("1.0", Deprecated = true)]                 // This is API v1, and it's deprecated
    [Authorize()]
    [Obsolete("Removed in API version 2.0")]               // Tell the compiler it's deprecated
    public partial class PatientAppController : ControllerBase
    { ... }

PatientAppV 2控制器

[ApiController]
    [Route("v{version:apiVersion}/PatientApp/[action]")]   // Rout: https://example.com/v2/PatientApp/SomeAction
    [ApiVersion("2.0")]                                    // This is API v2
    [Authorize()]
    public partial class PatientAppController : ControllerBase
    { ... }

我在Program.cs中添加了这个额外的配置:
是:

// -- Configure the HTTP request pipeline
app.UseSwagger();
app.UseSwaggerUI();

添加了Swagger终点:

// -- Configure the HTTP request pipeline
app.UseSwagger();
app.UseSwaggerUI(options => {
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "Indigo Health API V1");
    options.SwaggerEndpoint("/swagger/v2/swagger.json", "Indigo Health API V2");
});

现在,Swagger显示器很奇怪

“版本1”页面看起来是正确的:

但“版本2”页面(从页面顶部的下拉列表中选择“靛蓝Health API V2”)显示控制器名称的损坏版本(PatientAppV-不知道为什么不是PatientAppV 2):

终于...问题来了

如何更改Swagger显示的“section”名称

我希望Swagger在上面显示的页面上将与我的PatientAppV2Controller关联的节名显示为PatientApp,而不是PatientAppV。如何操作?

pbpqsu0x

pbpqsu0x1#

感谢Tiny Wang,是他给我指出了this SO answer
显然,Swagger文档生成器根据控制器类的名称对“组”标签(“PatientApp”,“Provider”等)进行假设。如果您希望拥有同一控制器的不同“版本”,则控制器类应命名为{Group}n{Controller},其中{Group}是显示在Swagger UI中的文本。
在我的例子中,我将两个受影响的控制器类重命名为PatientApp1ControllerPatientApp2Controller。现在,Swagger UI在两个版本的文档中显示PatientApp“组”。
顺便说一句,如果有人阅读这篇文章,可以发表评论或编辑这个答案,指向描述这种行为的文档,我将永远感激!

相关问题