在 .Net Core 中按项目对 Swagger 进行分组

Question

我正在开发一个名为“主项目”的项目。我在那里至少有 10 个不同的小项目，这个项目可能会增长。我对所有这些项目只有一个招摇，因为所有这些项目都只使用一个 dotnet 核心 Web 应用程序来进行泛化。

例如，假设我有名为 SchoolJob 的项目和名为 HospitalJob 的项目。 SchoolJob 有三个不同的端点，分别命名为 GetStudents、TakeStudents、GetPayment 和 HostpitalJob 有两个端点分别命名为 GetDoctors 和 GetNurses。这两个不同的项目将出现在一个像这样招摇的 UI 中：

 - ../schooljob/getstudents
 - ../schooljob/takestudents 
 - ../schooljob/getpayment
 - ../hospitaljob/getdoctors
 - ../hospitaljob/getnurses

我想要做的是在一个 dotnet core web 项目中设置多个不同的 swagger 页面，或者将一个 swagger 分组，以便它们可以在不同的页面/或同一页面上看到，但不是在同一时间。

../mainproject/swagger1/index.html 或 mainproject/swagger/schooljob UI 应该是这样的：

 - ../schooljob/getstudents
 - ../schooljob/takestudents 
 - ../schooljob/getpayment

../mainproject/swagger2/index.html 或 mainproject/swagger/hospitaljob UI 应该是这样的

 - ../hospitaljob/getdoctors
 - ../hospitaljob/getnurses

// Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    c.SwaggerDoc("schooljob", new OpenApiInfo
    {
        Version = "schooljob",
        Title = "School Job"
    });
    c.SwaggerDoc("hospitaljob", new OpenApiInfo
    {
        Version = "hospitaljob",
        Title = "Hospital Job"
    });
    // c.AddSecurityDefinition... and other swagger configurations
}   
public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IServiceProvider serviceProvider)
{
    app.UseSwagger(c =>
    {
        c.RouteTemplate = "mainproject/swagger/{documentname}/swagger.json";
    });
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/mainproject/swagger/schooljob/swagger.json", "School Job");
        c.SwaggerEndpoint("/mainproject/swagger/hospitaljob/swagger.json", "Hospital Job");
        c.RoutePrefix = "mainproject/swagger";
        /c second prefix how?
    });
}

// SchoolController.cs

[HttpPost("schooljob/getstudents")]
[ApiExplorerSettings(GroupName = "schooljob")]
public JsonResult GetStudents([FromBody]OnaySayfasiId onaySayfasi)
{ ... }

// HospitalController.cs

[HttpPost("hospitaljob/getdoctors")]
[ApiExplorerSettings(GroupName = "hospitaljob")]
public JsonResult GetDoctors([FromBody]OnaySayfasiId onaySayfasi)
{ ... }

顺便说一句，我尝试使用 Api 版本分组，但我又看到了所有这些端点。有什么方法可以做到吗？

Answer 1

我知道你遗漏了什么，你使用了错误的控制器属性，在这里你可以做什么：

• 在控制器中，您必须使用[ApiVersion] 而不是[ApiExplorerSettings(GroupName = ...)] 属性。组是不同的，我猜它们是关于在 Swagger 页面的同一部分下对端点进行分组。
• 当方法参数需要版本时，保持一致。 OpenApiInfo、SwaggerEndpoint、ApiVersion 需要相同的字符串，例如 schooljob 而不是 School Job。

我想如果你更新你的代码如下：

// Startup.cs

app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/mainproject/swagger/schooljob/swagger.json", "schooljob");
        c.SwaggerEndpoint("/mainproject/swagger/hospitaljob/swagger.json", "hospitaljob");
        c.RoutePrefix = "mainproject/swagger";
        // No need for 2nd route prefix as there is only one Swagger page,
        // the content of the page gets updated when selecting a different version in the combobox.
    });

/* This line may be required in ConfigureServices method, give it a try */
/* services.AddApiVersioning(); */

// SchoolController.cs

[HttpPost("schooljob/getstudents")]
[ApiVersion("schooljob")]
public JsonResult GetStudents([FromBody]OnaySayfasiId onaySayfasi)
{ ... }

希望它能解决你的问题！