在 asp.net core 3.1 web api 中，分组和版本控制在 swagger 中不能很好地协同工作 [英] Grouping and Versioning not working well together in swagger in asp.net core 3.1 web api

问题描述

我正在使用 Asp.Net Core 3.1 来构建我的 API.我正在使用 swagger 为我的 API 生成文档.我决定根据控制器对我的 swagger 文档进行分组.所以我最终这样做了，

I'm using Asp.Net Core 3.1 to build my API. I'm using swagger to generate document for my API. I decided to do grouping on my swagger document based on controller. So I ended up doing like this,

启动 - 配置服务:

options.SwaggerDoc(
    "LibraryOpenAPISpecificationCategories",
    ...

启动 - 配置:

options.SwaggerEndpoint(
    "/swagger/LibraryOpenAPISpecificationCategories/swagger.json",
    "Library API (Categories)");

控制器:

[Route("api/categories")]
[ApiController]
[ApiExplorerSettings(GroupName = "LibraryOpenAPISpecificationCategories")]
public class CategoriesController : ControllerBase

到目前为止一切正常.当我添加版本控制时，Swagger 文档停止显示控制器中的方法.我试图在版本内进行分组，以便每个版本都有这样的组，

Until this point everything was working fine. When I added versioning the Swagger document stopped displaying the methods in the controller. I was trying to bring grouping inside version so that each version will have the groups like,

V1 -> LibraryOpenAPISpecificationCategories

V1 -> LibraryOpenAPISpecificationCategories

V1 -> LibraryOpenAPISpecificationItems

V1 -> LibraryOpenAPISpecificationItems

V2 -> LibraryOpenAPISpecificationCategories

V2 -> LibraryOpenAPISpecificationCategories

V2 -> LibraryOpenAPISpecificationItems

V2 -> LibraryOpenAPISpecificationItems

这是我做的，

启动 - 配置服务:

services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VV";
});

services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
});

var apiVersionDescriptionProvider =
    services.BuildServiceProvider().GetService<IApiVersionDescriptionProvider>();

services.AddSwaggerGen(options =>
{
    foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(
            $"LibraryOpenAPISpecificationCategories{description.GroupName}",
            ...

启动 - 配置:

app.UseSwaggerUI(options =>
{
    foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
    {
        options.SwaggerEndpoint(
            $"/swagger/LibraryOpenAPISpecificationCategories{description.GroupName}/swagger.json",
            $"Library API (Categories) {description.GroupName.ToUpperInvariant()}");

控制器:

[Route("api/categories")]
[ApiController]
[ApiExplorerSettings(GroupName = "LibraryOpenAPISpecificationCategories")]
public class CategoriesController : ControllerBase

swagger 文档中没有显示错误.请帮助我解决我哪里出错了.我错过了什么吗?

No error is displayed in swagger document. Please assist me on where I'm going wrong. Am I missing anything?

推荐答案

经过一些分析，我发现我在 ConfigureServices 中的 AddSwaggerGen 中遗漏了 DocInclusionPredicate.

After some analysis, I figured out that I missed DocInclusionPredicate in AddSwaggerGen in my ConfigureServices.

我是这样解决的，

options.DocInclusionPredicate((documentName, apiDescription) =>
{
    var actionApiVersionModel = apiDescription.ActionDescriptor
    .GetApiVersionModel(ApiVersionMapping.Explicit | ApiVersionMapping.Implicit);

    var apiExplorerSettingsAttribute = (ApiExplorerSettingsAttribute)apiDescription.ActionDescriptor.EndpointMetadata.First(x => x.GetType().Equals(typeof(ApiExplorerSettingsAttribute)));

    if (actionApiVersionModel == null)
    {
        return true;
    }

    if (actionApiVersionModel.DeclaredApiVersions.Any())
    {
        return actionApiVersionModel.DeclaredApiVersions.Any(v =>
        $"{apiExplorerSettingsAttribute.GroupName}v{v.ToString()}" == documentName);
    }
    return actionApiVersionModel.ImplementedApiVersions.Any(v =>
        $"{apiExplorerSettingsAttribute.GroupName}v{v.ToString()}" == documentName);
});

希望这对那里的人有所帮助.

Hope this helps someone out there.

这篇关于在 asp.net core 3.1 web api 中，分组和版本控制在 swagger 中不能很好地协同工作的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！