Dotnet、Swagger 未正确显示版本“1.0”信息

Question

我有一个 C# 项目，其中定义了版本“1.0”、“1.1”和“1.2-rc1”。该api适用于所有版本的api，但是swagger不显示版本“1.0”的信息，它只显示“规范中没有定义的操作！”，swagger确实显示版本“1.1”和“1.2-”的正确信息rc1”。有人可以看到我在设置招摇信息时做错了什么吗？

卷曲测试：

V1.0 招摇信息：

V1.1 招摇信息：

程序.cs

using Asp.Versioning;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using Swashbuckle.AspNetCore.SwaggerUI;

namespace TestSwagger
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var builder = WebApplication.CreateBuilder(args);

            builder.Services.AddControllers();
            builder.Services.AddEndpointsApiExplorer();

            builder.Services.AddApiVersioning(options =>
            {
                options.AssumeDefaultVersionWhenUnspecified = false;
                options.ReportApiVersions = true;
                options.ApiVersionReader = ApiVersionReader.Combine(new UrlSegmentApiVersionReader());
            })
            .AddApiExplorer(options =>
            {
                // Add the versioned API explorer, which also adds IApiVersionDescriptionProvider service
                // note: the specified format code will format the version as "'v'major[.minor][-status]"
                options.GroupNameFormat = "'v'VVV";
                options.SubstituteApiVersionInUrl = true;
            });

            builder.Services.AddSwaggerGen(action =>
                DefinedApiVersion.GetAllApiVersionValues().ForEach(value =>
                    SetSwaggerDocInfo(action, value)
                )
            );

            builder.Services.AddControllers();

            var app = builder.Build();

            if (app.Environment.IsDevelopment())
            {
                app.UseSwagger();
                app.UseSwaggerUI(action =>
                {
                    DefinedApiVersion.GetAllApiVersionValues().ForEach(value => AddSwaggerEndpoint(action, value));
                    action.DisplayRequestDuration();
                });
            }

            app.UseHttpsRedirection();

            app.UseAuthorization();

            app.MapControllers();

            app.Run();
        }

        private static void AddSwaggerEndpoint(SwaggerUIOptions action, string apiVersionStr)
        {
            string apiVersionStrWithV = "v" + apiVersionStr;
            action.SwaggerEndpoint($"/swagger/{apiVersionStrWithV}/swagger.json", $"A small test API {apiVersionStrWithV}");
        }

        private static void SetSwaggerDocInfo(SwaggerGenOptions options, string apiVersionStr)
        {
            string apiVersionStrWithV = "v" + apiVersionStr;
            options.SwaggerDoc(apiVersionStrWithV, new OpenApiInfo
            {
                Version = apiVersionStrWithV,
                Title = $"A Test API {apiVersionStrWithV}",
                Description = "An dotnet core web api test ",
                TermsOfService = new Uri("https://localhost/terms"),
                Contact = new OpenApiContact { Name = "Contact", Url = new Uri("http://localhost/contact") },
                License = new OpenApiLicense { Name = "License", Url = new Uri("http://localhost/license") }
            });
        }

    }
}

测试控制器.cs：

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;

namespace TestSwagger.Controllers
{
    [ApiVersion(DefinedApiVersion.V1_0)]
    [ApiVersion(DefinedApiVersion.V1_1)]
    [ApiVersion(DefinedApiVersion.V1_2)]
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]")]
    public class TestController : ControllerBase
    {
        [MapToApiVersion(DefinedApiVersion.V1_0)]
        [MapToApiVersion(DefinedApiVersion.V1_1)]
        [MapToApiVersion(DefinedApiVersion.V1_2)]
        [HttpGet("Method1")]
        public string Method1()
        {
            return "1";
        }
        [MapToApiVersion(DefinedApiVersion.V1_1)]
        [MapToApiVersion(DefinedApiVersion.V1_2)]
        [HttpGet("Method2")]
        public string Method2()
        {
            return "2";
        }
        [MapToApiVersion(DefinedApiVersion.V1_2)]
        [HttpGet("Method3")]
        public string Method3()
        {
            return "3";
        }
    }
}

DefinedApiVersions.cs：

using System.Reflection;

namespace TestSwagger
{

    public static class DefinedApiVersion
    {
        public const string V1_0 = "1.0";
        public const string V1_1 = "1.1";
        public const string V1_2 = "1.2-rc1";

        public static List<string> GetAllApiVersionValues()
        {
            return typeof(DefinedApiVersion)
           .GetFields(BindingFlags.Public | BindingFlags.Static | BindingFlags.FlattenHierarchy)
           .Where(x => x.IsLiteral && x.FieldType == typeof(string))
           .Select(x => x.GetRawConstantValue()?.ToString() ?? string.Empty)
           .ToList();
        }
    }
}

Answer 1

由于

options.GroupNameFormat

设置为“VVV”，因此您的版本“1.0”格式为

"1"

。正如您在评论中提到的，您可以将

V1_0

字符串更改为

"1"

以使 Swagger 数据显示，或者您可以将 版本格式 更改为

"VV"

（主要版本和次要版本）以继续使用

"1.0" 

.