C# .net core 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)
    {
        var controllerNamespace = controller.ControllerType.Namespace; // e.g. "Controllers.V1"
        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");
});

在我的控制器中，我需要像这样配置

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

Answer 2

问题是我的 swagger 配置中有以下行：

services.AddSwaggerGen(c =>
{
...
c.DocInclusionPredicate((_, api) => !string.IsNullOrWhiteSpace(api.GroupName));
...
});

文档包含预测总是返回 true。这就是为什么它将所有端点添加到所有文档中的原因。我们不需要 doc 包含预测，因为我们已经通过 ApiExplorerGroupPerVersionConvention 将 and-points 添加到更正组