由ASP.NET Core WebApi添加Swagger报错引发的探究
缘起
在使用ASP.NET Core进行WebApi项目开发的时候，相信很多人都会使用Swagger作为接口文档呈现工具。相信大家也用过或者了解过Swagger，这里咱们就不过多的介绍了。本篇文章记录一下，笔者在使用ASP.NET Core开发Api的过程中，给接口整合Swagger过程中遇到的一个异常，笔者抱着好奇的心态研究了一下异常的原因，并解决了这个问题。在这个过程中笔者学到了一些新的技能，得到了一些新的知识，便打算记录一下，希望能帮助到更多的人。
示例
从项目渊源上说起，笔者所在项目，很多都是从.Net FrameWorkd的老项目迁移到ASP.NET Core上来的，这其中做了很多兼容的处理，来保证尽量不修改原有的业务代码，这其中就包含了WebApi相关的部分，这里我们用简单的示例描述现有WebApi的Controller的情况，大致写法如下
[Route("api/[controller]/[action]")]
[ApiController]
public class OrderController : ControllerBase
{
private List orderDtos = new List();
public OrderController()
{
orderDtos.Add(new OrderDto { Id = 1,TotalMoney=222,Address="北京市",Addressee="me",From="淘宝",SendAddress="武汉" });
orderDtos.Add(new OrderDto { Id = 2, TotalMoney = 111, Address = "北京市", Addressee = "yi", From = "京东", SendAddress = "北京" });
orderDtos.Add(new OrderDto { Id = 3, TotalMoney = 333, Address = "北京市", Addressee = "yi念之间", From = "天猫", SendAddress = "杭州" });
}
///
/// 获取订单数据
///
public OrderDto Get(long id)
{
return orderDtos.FirstOrDefault(i => i.Id == id);
}
///
/// 添加订单数据
///
public IActionResult Add(OrderDto orderDto)
{
orderDtos.Add(orderDto);
return Ok();
}
///
/// 添加订单数据
///
public IActionResult Edit(long id, OrderDto orderDto)
{
var order = orderDtos.FirstOrDefault(i => i.Id == id);
if (order == null)
{
return NotFound();
}
order.Address = orderDto.Address;
order.From = orderDto.From;
return Ok();
}
///
/// 删除订单数据
///
public IActionResult Delete(long id)
{
var order = orderDtos.FirstOrDefault(i=>i.Id==id);
if (order == null)
{
return NotFound();
}
orderDtos.Remove(order);
return Ok();
}
}
虽然是笔者写的demo，但是大致是这种形式，而且直接通过ASP.NET Core运行起来也没有任何的问题，调用也不会出现任何异常。当项目开发完成后，给项目添加Swagger，笔者用的是Swashbuckle.AspNetCore这个组件，添加Swagger的方式大致如下，首先是在Startup类的ConfigureServices方法中添加以下代码
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "OrderApi",
Description = "订单服务接口"
});
var xmlCommentFile = $"{AppContext.BaseDirectory}OrderApi.xml";
if (File.Exists(xmlCommentFile))
{
c.IncludeXmlComments(xmlCommentFile);
}
});
添加完成之后，在Configure方法中开启Swagger中间件，具体代码如下
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "OrderApi");
});
添加完成之后，运行起来项目打开Swagger地址http://localhost:5000/swagger结果直接弹出了一个红色浮窗，看样子有异常，打开.Net Core控制台窗口看到了如下异常
fail: Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware[1] An unhandled exception has occurred while executing the request.
Swashbuckle.AspNetCore.SwaggerGen.SwaggerGeneratorException: Ambiguous HTTP method for action OrderApi.Controllers.OrderController.Get (OrderApi).
Actions require an explicit HttpMethod binding for Swagger/OpenAPI 3.0
at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.GenerateOperations(IEnumerable`1 apiDescriptions, SchemaRepository schemaRepository)
at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.GeneratePaths(IEnumerable`1 apiDescriptions, SchemaRepository schemaRepository)
at Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.GetSwagger(String documentName, String host, String basePath)
at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)
其中核心的关键词汇就是Ambiguous HTTP method for action OrderApi.Controllers.OrderController.Get (OrderApi). Actions require an explicit HttpMethod binding for Swagger/OpenAPI 3.0笔者用尽毕生的英语修为，了解到其大概意思是Swagger/OpenAPI 3.0要求Action上必须绑定HttpMethod相关Attribute，否则就报这一大堆错误。这里的HttpMethod其实就是咱们常用HttpGet、HttpPost、HttpPut、HttpDelete相关的Attribute。正常逻辑来说那就给每个Action添加HttpMethod呗，但是往往情况就出现在不正常的时候。因为项目是迁移的老项目，先不说私自改了别人代码带来的甩锅问题，公司的WebApi项目很多，这意味着Action很多，如果一个项目一个项目的去找Action添加HttpMethod可是一个不小的工作量，而且开发人员工作繁忙，基本上不会抽出来时间去修改这些的，因为这种只是Swagger不行，但是对于WebApi本身来说这种写法没有任何的问题，也不会报错，只是看起来不规范。那该怎么办呢？
探究源码
又看了看异常决定从源码入手,通过控制台报出的异常可以看到报错的最初位置是在Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator.GenerateOperations(IEnumerable1 apiDescriptions, SchemaRepository schemaRepository)`那就从这里准备入手了。
Swashbuckle.AspNetCore入手
在GitHub上找到Swashbuckle.AspNetCore仓库位置，近期GitHub不太稳定，除了梯子貌似也没有很好的办法，多刷新几次将就着用吧，由异常信息可知抛出异常所在的位置SwaggerGenerator类的GenerateOperations方法直接找到源码位置[点击查看源码????[1]]代码如下
private IDictionary GenerateOperations(IEnumerable apiDescriptions,
SchemaRepository schemaRepository)
{
//根据HttpMethod分组
var apiDescriptionsByMethod = apiDescriptions
.OrderBy(_options.SortKeySelector)
.GroupBy(apiDesc => apiDesc.HttpMethod);
var operations = new Dictionary();
foreach (var group in apiDescriptionsByMethod)
{
var httpMethod = group.Key;
if (httpMethod == null)
//异常位置在这里
throw new SwaggerGeneratorException(string.Format(
"Ambiguous HTTP method for action - {0}. " +
"Actions require an explicit HttpMethod binding for Swagger/OpenAPI 3.0",
group.First().ActionDescriptor.DisplayName));
if (group.Count() > 1 && _options.ConflictingActionsResolver == null)
throw new SwaggerGeneratorException(string.Format(
"Conflicting method/path combination \"{0} {1}\" for actions - {2}. " +
"Actions require a unique method/path combination for Swagger/OpenAPI 3.0. Use ConflictingActionsResolver as a workaround",
httpMethod,
group.First().RelativePathSansQueryString(),
string.Join(",", group.Select(apiDesc => apiDesc.ActionDescriptor.DisplayName))));
var apiDescription = (group.Count() > 1) ? _options.ConflictingActionsResolver(group) : group.Single();
operations.Add(OperationTypeMap[httpMethod.ToUpper()], GenerateOperation(apiDescription, schemaRepository));
};
return operations;
}
httpMethod属性的数据源来自IEnumerable集合，顺着调用关系往上找，最后发现ApiDescription来自IApiDescriptionGroupCollectionProvider而它来自于构造函数注入进来的
private readonly IApiDescriptionGroupCollectionProvider _apiDescriptionsProvider;
private readonly ISchemaGenerator _schemaGenerator;
private readonly SwaggerGeneratorOptions _options;
public SwaggerGenerator(
SwaggerGeneratorOptions options,
IApiDescriptionGroupCollectionProvider apiDescriptionsProvider,
ISchemaGenerator schemaGenerator)
{
_options = options ?? new SwaggerGeneratorOptions();
_apiDescriptionsProvider = apiDescriptionsProvider;
_schemaGenerator = schemaGenerator;
}
看名字也知道IApiDescriptionGroupCollectionProvider是专门服务于Api描述相关的，在Swashbuckle.AspNetCore仓库中造了下没发现相关定义，于是用VS找到引用发现定义如下
namespace Microsoft.AspNetCore.Mvc.ApiExplorer
{
public interface IApiDescriptionGroupCollectionProvider
{
ApiDescriptionGroupCollection ApiDescriptionGroups { get; }
}
}
转战aspnetcore
看命名空间IApiDescriptionGroupCollectionProvider居然是AspNetCore.Mvc下的，也就是说来自AspNetCore自身，跑到AspNetCore的核心仓库搜索了一下代码找到如下位置代码[点击查看源码????[2]]
internal static void AddApiExplorerServices(IServiceCollection services)
{
services.TryAddSingleton();
services.TryAddEnumerable(
ServiceDescriptor.Transient());
}
而AddApiExplorerServices方法是在当前类的AddApiExplorer扩展方法中被调用的
public static IMvcCoreBuilder AddApiExplorer(this IMvcCoreBuilder builder)
{
AddApiExplorerServices(builder.Services);
return builder;
}
看到IMvcCoreBuilder接口，我们就应该感觉到这是Mvc的核心接口扩展方法，但是趋于好奇心还是往上找了一下，发现确实是跟着ASP.NET Core土生土长的实现，最终位置如下[点击查看源码????[3]]
private static IMvcCoreBuilder AddControllersCore(IServiceCollection services)
{
return services
.AddMvcCore()
.AddApiExplorer()
.AddAuthorization()
.AddCors()
.AddDataAnnotations()
.AddFormatterMappings();
}
微软想的还是比较周到的，居然在ASP.NET Core的核心位置，加入了IApiDescriptionGroupCollectionProvider这种操作，在IApiDescriptionGroupCollectionProvider的示例中包含了当前Api项目有关Controller和Action相关的信息，而Swagger的Doc文档也就是咱们看到的swagger.json正是基于这些数据信息组装而来。
IApiDescriptionGroupCollectionProvider还是比较实用，如果在不知道这个操作存在的情况下，我们获取WebApi的Controller或Action相关的信息，首先想到的就是反射Controller得到这些，如今有了IApiDescriptionGroupCollectionProvider我们可以在IOC容器中直接获取这个接口的实例，获取Controller和Action的信息。
解决问题
我们找到了问题的根源，可以下手解决问题了，其本质问题是Swagger通过ApiDescription获取Action的HttpMethod信息，但是我们项目由于各种原因，在Action上并没有添加HttpMethod相关的Attribute，所以我们只能从ApiDescription入手，好在我们可以在IOC容器中获取到IApiDescriptionGroupCollectionProvider的实例，从这里入手扩展一个方法，具体实现如下
///
/// action没有httpmethod attribute的情况下根据action的开头名称给与默认值
///
/// IApplicationBuilder
/// 默认给定的HttpMethod
public static void AutoHttpMethodIfActionNoBind(this IApplicationBuilder app, string defaultHttpMethod = null)
{
//从容器中获取IApiDescriptionGroupCollectionProvider实例
var apiDescriptionGroupCollectionProvider = app.ApplicationServices.GetRequiredService();
var apiDescriptionGroupsItems = apiDescriptionGroupCollectionProvider.ApiDescriptionGroups.Items;
//遍历ApiDescriptionGroups
foreach (var apiDescriptionGroup in apiDescriptionGroupsItems)
{
foreach (var apiDescription in apiDescriptionGroup.Items)
{
if (string.IsNullOrEmpty(apiDescription.HttpMethod))
{
//获取Action名称
var actionName = apiDescription.ActionDescriptor.RouteValues["action"];
//默认给定POST
string methodName = defaultHttpMethod ?? "POST";
//根据Action开头单词给定HttpMethod默认值
if (actionName.StartsWith("get", StringComparison.OrdinalIgnoreCase))
{
methodName = "GET";
}
else if (actionName.StartsWith("put", StringComparison.OrdinalIgnoreCase))
{
methodName = "PUT";
}
else if (actionName.StartsWith("delete", StringComparison.OrdinalIgnoreCase))
{
methodName = "DELETE";
}
apiDescription.HttpMethod = methodName;
}
}
}
}
写完上面的代码后，抱着试试看的心情，因为不清楚这波操作好不好使，将扩展方法引入到Configure方法中，为了清晰和Swagger中间件放到一起后，效果如下
if (!env.IsProduction())
{
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "OrderApi");
});
//给没有配置httpmethod的action添加默认操作
app.AutoHttpMethodIfActionNoBind();
}
加完之后重新运行项目，打开swagger地址http://localhost:5000/swagger没有异常，在Swagger上调用了接口试了一下，没有任何问题。这样的话可以做到只添加一个扩展方法就能解决问题，而不需要挨个Action进行添加HttpMethod。如果想需要更智能的判断Action默认的HttpMethod需要如何定位，直接修改AutoHttpMethodIfActionNoBind扩展方法，因为我们WebApi项目的Action大部分调用方式都是HttpPost，所以这里的逻辑我写的比较简单。
后续小插曲
通过上面的方式解决了Swagger报错之后，在后来无意中翻看Swashbuckle.AspNetCore文档的时候发现了IDocumentFilter这个Swagger过滤器，想着如果能通过过滤器的方式去解决这个问题会更优雅。我们都知道过滤器的作用，而这个过滤器通过看名字我们可以知道他是在生成SwaggerDoc的时候可以对Doc数据进行处理，于是尝试写了一个过滤器，实现如下
public class AutoHttpMethodOperationFitler : IDocumentFilter
{
private readonly string _defaultHttpMethod;
public AutoHttpMethodOperationFitler(string defaultHttpMethod = null)
{
_defaultHttpMethod = defaultHttpMethod;
}
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
//通过DocumentFilterContext上下文可以获取到ApiDescription集合
foreach (var apiDescription in context.ApiDescriptions)
{
//为null说明没有给Action添加HttpMethod
if (string.IsNullOrEmpty(apiDescription.HttpMethod))
{
//这些逻辑是和AutoHttpMethodIfActionNoBind扩展方法保持一致的
var actionName = apiDescription.ActionDescriptor.RouteValues["action"];
string methodName = "POST";
if (actionName.StartsWith("get", StringComparison.OrdinalIgnoreCase))
{
methodName = "GET";
}
else if (actionName.StartsWith("put", StringComparison.OrdinalIgnoreCase))
{
methodName = "PUT";
}
else if (actionName.StartsWith("delete", StringComparison.OrdinalIgnoreCase))
{
methodName = "DELETE";
}
apiDescription.HttpMethod = methodName;
}
}
}
}
编写完成之后再AddSwaggerGen方法中注册AutoHttpMethodOperationFitler过滤器，如下所示
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "OrderApi",
Description = "订单服务接口"
});
//这里注册DocumentFilter
c.DocumentFilter();
var xmlCommentFile = $"{AppContext.BaseDirectory}OrderApi.xml";
if (File.Exists(xmlCommentFile))
{
c.IncludeXmlComments(xmlCommentFile);
}
});
忙活完这一波之后注释掉AutoHttpMethodOperationFitler扩展方法，添加AutoHttpMethodOperationFitler过滤器，然后运行一波，打开Swagger地址。不过很遗憾还是会报Actions require an explicit HttpMethod binding for Swagger/OpenAPI 3.0这个异常，想了想为啥还会报这个异常无果后，决定还是翻看源码看一下，这一看果然找到了原因，代码如下[点击查看源码????[4]]
var swaggerDoc = new OpenApiDocument
{
Info = info,
Servers = GenerateServers(host, basePath),
//出现异常的代码方法在这里被调用
Paths = GeneratePaths(applicableApiDescriptions, schemaRepository),
Components = new OpenApiComponents
{
Schemas = schemaRepository.Schemas,
SecuritySchemes = new Dictionary(_options.SecuritySchemes)
},
SecurityRequirements = new List(_options.SecurityRequirements)
};
//执行IDocumentFilter Apply方法的地方在这里
var filterContext = new DocumentFilterContext(applicableApiDescriptions, _schemaGenerator, schemaRepository);
foreach (var filter in _options.DocumentFilters)
{
filter.Apply(swaggerDoc, filterContext);
}
通过上面的源码可以看到，针对数据源信息是否规范的校验，是在执行IDocumentFilter过滤器的Apply方法之前进行的，所以我们在DocumentFilter处理HttpMethod的问题是解决不了的。到这里自己也明白了AutoHttpMethodOperationFitler目前是解决这个问题能想到的最好方式，暂时算是没啥遗憾了。
总结
本篇文章讲解了在给ASP.NET Core添加Swagger的时候遇到的一个异常而引发的对相关源码的探究，并最终解决这个问题，这里我们Get到了一个比较实用的技能，ASP.NET Core内置了IApiDescriptionGroupCollectionProvider实现，通过它我们可以很便捷的获取到WebApi中关于Controller和Action的元数据信息，而这些信息方便我们生成帮助文档或者生成调用代码是非常实用的。
如果你对源码感兴趣，或者有通过看源码解决问题的意识的话，这种方式还是比较有效的，因为我们作为程序员最懂的还是代码，而代码的报错当然也得看着代码解决。解决这类问题也没啥特别好的技巧，通过异常堆栈找到报错的原始位置，顺序需要用到的代码一步一步的往上找，直到找到源头。而这也正是看源码的乐趣，要么好奇驱使，要么解决问题。更好的理解代码，就有更好的方式解决问题，就比如我没办法挨个给Action添加HttpMethod所以找到另一个途径解决问题。
References
[1] 点击查看源码????: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/v6.1.4/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs#L98[2] 点击查看源码????: https://github.com/dotnet/aspnetcore/blob/v5.0.7/src/Mvc/Mvc.ApiExplorer/src/DependencyInjection/MvcApiExplorerMvcCoreBuilderExtensions.cs#L34[3] 点击查看源码????: https://github.com/dotnet/aspnetcore/blob/v5.0.7/src/Mvc/Mvc/src/MvcServiceCollectionExtensions.cs#L141[4] 点击查看源码????: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/v6.1.4/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs#L47