使用Microsoft.AspNetCore.Mvc.Versioning、Swashbuckle.AspNetCore和MaptoApiVersion

Question

我在以下使用MapToApiVersion时遇到了问题。在http://localhost:5000/swagger中，1.0Docs和2.0Docs正确地呈现了swagger，并提供了相应的swagger.json文件。3.0文档无法呈现，swagger.json文件似乎没有生成。

所有三个版本的实际服务都已启动并正常运行。如果我从邮递员那里击中它，我就会得到我期望的反应。

这是运行1.1.1-rc1的Mvc.Versioning和1.0.0的Swashbuckle.AspNetCore。下面是完整的.csproj

https://github.com/senften/AspNetCoreVersionedWebApi/tree/maptoapiversion上的完整代码

在Visual代码中调试时，我不会看到任何错误或有任何异常。我是把启动或声明搞砸了，还是仅仅是在垫片或垫圈中遇到了一个bug？

using Microsoft.AspNetCore.Mvc;
using VersionedWebApi.Model;

namespace VersionedWebApi.Controllers
{
    /// <summary>
    /// GoodByeController, just saying Goodbye!
    /// </summary>
    [ApiVersion("1.0", Deprecated = true)]
    [ApiVersion("3.0")]
    [Route("api/v{api-version:apiVersion}/[controller]")]
    public class GoodByeController : Controller
    {
        /// <summary>
        /// Default Get call returning Goodbye world!
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        [ProducesResponseType(typeof(GoodByeWorldModel), 200)]
        [ProducesResponseType(typeof(void), 404)]
        public GoodByeWorldModel Get()
        {
            return new GoodByeWorldModel();
        }

        /// <summary>
        /// Default Get call returning Goodbye world!
        /// </summary>
        /// <returns></returns>
        [HttpGet, MapToApiVersion("3.0")]
        [ProducesResponseType(typeof(VersionedWebApi.Model.v3.GoodByeWorldModel), 200)]
        [ProducesResponseType(typeof(void), 404)]
        public VersionedWebApi.Model.v3.GoodByeWorldModel GetV3()
        {
            return new VersionedWebApi.Model.v3.GoodByeWorldModel();
        }
    }
}

startup.cs

using System.Xml.XPath;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.ApplicationParts;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using SwashbuckleAspNetVersioningShim;

namespace VersionedWebApi
{
    public class Startup
    {
        public Startup()
        {
        }

        public IConfigurationRoot Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            // Add framework services.
            var mvcBuilder = services.AddMvc();
            services.AddMvcCore().AddVersionedApiExplorer();

            // Adds versioning capabilities, defaulting to version 1.0 calls if available
            services.AddApiVersioning(o =>
            {
                o.AssumeDefaultVersionWhenUnspecified = true;
                o.DefaultApiVersion = new ApiVersion(1, 0);
            });

            // Add generated documentation
            services.AddSwaggerGen(c =>
            {
                var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
                SwaggerVersioner.ConfigureSwaggerVersions(c, provider);
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, ApplicationPartManager partManager, IApiVersionDescriptionProvider provider)
        {
            // Generate swagger.json
            app.UseSwagger();

            // Let's enable SwaggerUI
            app.UseSwaggerUI(c =>
            {
                SwaggerVersioner.ConfigureSwaggerVersions(c, provider);
            });

            app.UseMvc();
            // This is new for v1.1 and is a behavioral breaking change from previous (including 1.1-beta)
            // See the release notes: https://github.com/Microsoft/aspnet-api-versioning/releases/tag/v1.1-rc1
            app.UseApiVersioning();
        }
    }
}

csproj文件

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp1.1</TargetFramework>
    <Company />
    <Description>A .NET Core Web API project demonstrating versioning a Web API and generating interactive documentation with Swagger.</Description>
    <RepositoryUrl>https://github.com/senften/AspNetCoreVersionedWebApi</RepositoryUrl>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile></DocumentationFile>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore" Version="1.1.2" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="1.1.3" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="1.1.0-rc1"/>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="1.0.0" />
    <PackageReference Include="SwashbuckleAspNetVersioningShim" Version="1.0.0-beta4"/>
  </ItemGroup>
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="1.0.0-msbuild3-final" />
  </ItemGroup>
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="1.0.0"/>
    <DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="*"/>
  </ItemGroup>

</Project>

Answer 1

需要对代码进行一些更改。

1)将下面的代码更改为

    [ApiVersion("3.0"), Route("api/v{api-version:apiVersion}/[controller]")]
    [Route("api/v{api-version:apiVersion}/[controller]")]
    public class HelloController : Controller
    { }


    [ApiVersion("3.0"), Route("api/v{api-version:apiVersion}/[controller]")]
    public class HelloController : Controller
    { }

2)添加MapToApiVersion 1.0以避免冲突

[HttpGet, MapToApiVersion("1.0")]
[ProducesResponseType(typeof(GoodByeWorldModel), 200)]
[ProducesResponseType(typeof(void), 404)]
public GoodByeWorldModel Get()
{
    return new GoodByeWorldModel();
}

Answer 2

您所遇到的问题是shim库的行为。

生成Swagger文档时，控制器上指定的ApiVersion将应用于其中的所有方法，在这些方法中，它们没有显式地设置为其他方法。在这个实例中，由于在MapToApiVersion方法上没有Get()属性，所以它被添加到V1和V3 Swagger文档中，因为这是控制器上指定的。这会在生成Swagger文档时导致过载错误。

好消息是，这是一个简单的修复，只需将[HttpGet, MapToApiVersion("1.0")]添加到您的Get()方法中，如下所示

/// <summary>
/// Default Get call returning Goodbye world!
/// </summary>
/// <returns></returns>
[HttpGet, MapToApiVersion("1.0")]
[ProducesResponseType(typeof(GoodByeWorldModel), 200)]
[ProducesResponseType(typeof(void), 404)]
public GoodByeWorldModel Get()
{
    return new GoodByeWorldModel();
}

然后，Get()方法将只被添加到V1文档中，您的代码的其余部分可以保持原样。

关于Shim在GitHub自述上的这种行为还有一些更多的细节