我有一个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包含几个控制器(PatientAppController
、ProviderController
和ServerInfoController
),每个控制器在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。如何操作?
1条答案
按热度按时间pbpqsu0x1#
感谢Tiny Wang,是他给我指出了this SO answer!
显然,Swagger文档生成器根据控制器类的名称对“组”标签(“PatientApp”,“Provider”等)进行假设。如果您希望拥有同一控制器的不同“版本”,则控制器类应命名为
{Group}n{Controller}
,其中{Group}
是显示在Swagger UI中的文本。在我的例子中,我将两个受影响的控制器类重命名为
PatientApp1Controller
和PatientApp2Controller
。现在,Swagger UI在两个版本的文档中显示PatientApp“组”。顺便说一句,如果有人阅读这篇文章,可以发表评论或编辑这个答案,指向描述这种行为的文档,我将永远感激!