C# .net 核心 swagger 尝试使用多个 API 版本，但所有端点都在所有文档中

Question

我们正在尝试将我们的 API 版本分离到不同的 Swagger 文档中。我们已按照 https://github.com/domaindrivendev/Swashbuckle.AspNetCore#generate-multiple-swagger-documents 中的描述配置了所有内容.

所以我们配置了两个这样的版本:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API - V1", Version = "v1" });
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API - V2", Version = "v2" });
})

我们还配置了在 swagger ui 中查看它们。像这样:

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API - V1");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API - V2");
});

为了在正确的版本中设置端点，我们使用以下约定:

public class ApiExplorerGroupPerVersionConvention : IControllerModelConvention
{
    public void Apply(ControllerModel controller)
    {
        // e.g. "Controllers.V1":
        var controllerNamespace = controller.ControllerType.Namespace; 
        var apiVersion = controllerNamespace.Split('.').Last().ToLower();

        controller.ApiExplorer.GroupName = apiVersion;
    }
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(c =>
        c.Conventions.Add(new ApiExplorerGroupPerVersionConvention())
    );
}

现在我们在 UI 中看到了这两个文档，我们可以转到 json 文件。这样就可以了。但是所有的终点都在两个文件中。我们期望在 v1 中看到 v1 端点，在 v2 中看到 v2 端点。但事实并非如此。如果我们调试约定，那么我们会看到它正确设置了组名。如果我们不设置组名，我们根本看不到端点。

所以这一切似乎都有效，除了它没有分开。我们错过了什么吗？

Answer 1

这就是我用多版本配置 swagger 的方式

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info
    {
        Version = "v1",
        Title = "Awesome CMS Core API V1",
        Contact = new Contact { Name = "Tony Hudson", Email = "", Url = "https://github.com/ngohungphuc" }
    });

    c.SwaggerDoc("v2", new Info
    {
        Version = "v2",
        Title = "Awesome CMS Core API V2",
        Contact = new Contact { Name = "Tony Hudson", Email = "", Url = "https://github.com/ngohungphuc" }
    });

    c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
});


app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint($"/swagger/v1/swagger.json", "Awesome CMS Core API V1");
    c.SwaggerEndpoint($"/swagger/v2/swagger.json", "Awesome CMS Core API V2");
});

在我的 Controller 中我需要这样配置

[ApiVersion("1.0")]
[ApiExplorerSettings(GroupName = "v1")]
[Route("api/v{version:apiVersion}/Account/")]