swagger2 返回Map 报错（swagger2配置）

有时候，我们的WebAPI可能会涉及到多版本管理，在开发新版本接口的同时又能保障老接口的稳定运行，那么这时候可能会涉及到两个版本的接口，一般我们会在接口上加个版本号，如：v1、v2.

我们来参考下百度地图API的格式

在.net core中，想给接口加上版本号，有多种方式:

• 1、通过URL Path Segment来实现;
• 2、通过HTTP Headers来实现;
• 3、通过QueryString来实现; 具体的实现可以去百度或者Bing。我个人喜欢使用第一种方式。这里，我们继续上个版本再引入一个组件:Microsoft.AspNetCore.Mvc.Versioning Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 现在我先在Controllers文件夹中分别创建v1、v2两个文件夹，用于存放两个版本的API,然后分别在v1和v2下面创建DemoV1Controller、DemoV2Controller两个Controller

DemoV1Controller

//当前Controller的版本号    [ApiVersion("1.0")]    //接口访问路径    [Route("api/v{version:apiVersion}/[controller]")]    [ApiController]    public class DemoV1Controller : ControllerBase    {        /// <summary>        /// 获取版本号        /// </summary>        /// <returns></returns>        [HttpGet("version")]        public string GetVerison() {            return "v1.0";        }    }

DemoV2Controller

 //当前Controller的版本号    [ApiVersion("2.0")]    //接口访问路径    [Route("api/v{version:apiVersion}/[controller]")]    [ApiController]    public class DemoV2Controller : ControllerBase    {        /// <summary>        /// 获取版本号        /// </summary>        /// <returns></returns>        [HttpGet("version")]        public string GetVerison()        {            return "v2.0";        }    }

接下来我们就去配置Swagger，因为配置代码有点多，所以最好是独立一个配置类,这里我新建一个名为ConfigureSwaggerOptions的配置类

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>    {        readonly IApiVersionDescriptionProvider provider;        public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) =>          this.provider = provider;        public void Configure(SwaggerGenOptions options)        {            foreach (var description in provider.ApiVersionDescriptions)            {                options.SwaggerDoc(description.GroupName, new OpenApiInfo                {                    Description = $"Demo API {description.ApiVersion} Description",                    Version = description.ApiVersion.ToString(),                    Title = $"Demo API 文档{description.ApiVersion}",                    Contact = new OpenApiContact() { Name = "eyiadmin", Email = "188781475@qq.com" },                    License = new OpenApiLicense                    {                        Name = "Apache 2.0",                        Url = new Uri("http://www.apache.org/licenses/LICENSE-2.0.html")                    }                });            }            var docXmlPath = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");            options.IncludeXmlComments(docXmlPath);        }    }

好了，现在去Startup.cs类的ConfigureServices注入上面的配置类

 public void ConfigureServices(IServiceCollection services)        {            services.AddApiVersioning();            services.AddVersionedApiExplorer(options => options.GroupNameFormat = "'v'VVV");            services.AddControllers();            services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();            services.AddSwaggerGen();        }

此时运行起来就可以看到我们的带版本号的新版接口文档，同时，我们可以点击右上角切换不同版本的接口文档

如果我们想要调试接口，点击每个接口里面的Try it out，输入对应的参数即可

多版本接口文档就记这么多了，接下来，我们继续在Swagger中添加Header Authorization

一般情况下，我们的Web API是使用Jwt来保障接口安全，当然还有很多其他的方式，我只是选择一种相对简单一些的方式。这里只是说怎么在Swagger调试的时候带上我们的Jwt Token，具体的Jwt实现，也请自己实现。

其实Swashbuckle已经给我们提供了很方便的API，只需要配置一下即可:

options.AddSecurityDefinition("bearer", new OpenApiSecurityScheme           {               Type = SecuritySchemeType.Http,               In = ParameterLocation.Header,               Name = "Authorization",               Scheme = "bearer",               BearerFormat = "JWT",               Description = "JWT Authorization header using the Bearer scheme.",           });           var req = new OpenApiSecurityRequirement();           req.Add(new OpenApiSecurityScheme           {               Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "bearer" }           }, new[] { "" });           options.AddSecurityRequirement(req);

可以看到接口列表右上角多了一个Authorize的图标，我们点击可以输入我们获取到的Jwt Token,在文本框内不需要输入Bearer关键字，Swagger会自动为我们加上Bearer关键字。

此时再来调用接口时，就会自动在我们的请求上加上authorization这个请求头

当然，也可以通过Swashbuckle.AspNetCore.Filters来添加请求头，另外，我们在开发WebApi的时候，也会有涉及到上传文件的场景，Swashbuckle也为我们提供好了API，我们新增一个文件上传接口

  /// <summary>        /// 上传文件        /// </summary>        /// <param name="file"></param>        /// <returns></returns>        [HttpPost("upload")]        public string UploadFile(IFormFile file)        {           return "";        }

然后在ConfigureSwaggerOptions新增一条配置

 options.MapType(typeof(IFormFile), () => new OpenApiSchema() { Type = "file", Format = "binary" });

这样一来，Swashbuckle会为我们生产相应的组件来供我们测试