.NetCore3 Swagger 使用 SchemaFilter 给你 API Swagger 自定义请求参数显示
NeverSettle101 2020-01-22 16:17:31 ?2104 ?收藏
分类专栏： .NetCore3+ 自定义属性
版权
.NetCore3+
同时被 2 个专栏收录
8 篇文章0 订阅
订阅专栏
自定义属性
2 篇文章0 订阅
订阅专栏
原理
通过 Attribute来获取特别的参数，需要忽略或者增加的都可以，然后再实现 ISchemaFilter，通过反射获取到这些Attributes，最后根据获取到的属性来给 OpenApiSchema删除或者添加属性
IOperationFilter
来源于命名空间：namespace Swashbuckle.AspNetCore.SwaggerGen
官方应用源码
具体代码
属性定义
首先，定义一个需要添加参数的属性
[AttributeUsage(AttributeTargets.Property)]
? ? public class SwaggerExcludeAttribute : Attribute
? ? {
? ? }
1
2
3
4
然后，实现 ISchemaFilter,添加对应的处理
public class SwaggerExcludeFilter : ISchemaFilter
? ? {
? ? ? ? public void Apply(OpenApiSchema schema, SchemaFilterContext context)
? ? ? ? {
? ? ? ? ? ? if (schema?.Properties?.IsNullOrEmpty() ?? true)
? ? ? ? ? ? {
? ? ? ? ? ? ? ? return;
? ? ? ? ? ? }
? ? ? ? ? ? var excludedProperties = context.Type.GetProperties();
? ? ? ? ? ? foreach (var property in excludedProperties)
? ? ? ? ? ? {
? ? ? ? ? ? ? ? var attributes = property.GetCustomAttributes(true);
? ? ? ? ? ? ? ? var excludeAttributes = attributes.OfType<SwaggerExcludeAttribute>();
? ? ? ? ? ? ? ? if (!excludeAttributes.IsNullOrEmpty()
? ? ? ? ? ? ? ? ? ? && schema.Properties.ContainsKey(property.Name))
? ? ? ? ? ? ? ? {
? ? ? ? ? ? ? ? ? ? schema.Properties.Remove(property.Name);
? ? ? ? ? ? ? ? }
? ? ? ? ? ? };
? ? ? ? }
? ? }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
最后在 Startup 中注入 Swagger 中间件的位置引入
//other codes
services.AddSwaggerGen(options =>
? ? ? ? ? ? {
? ? ? ? ? ? ? ? //options.OperationFilter<AddSwaggerBizParametersFilters>();
? ? ? ? ? ? ? ? options.SchemaFilter<SwaggerExcludeFilter>();
? ? ? ? ? ? ? ? // UseFullTypeNameInSchemaIds replacement for .NET Core
? ? ? ? ? ? ? ? //options.CustomSchemaIds(x => x.FullName);
? ? ? ? ? ? ? ? //options.DescribeAllEnumsAsStrings();
? ? ? ? ? ? });
//other codes
————————————————
版权声明：本文为CSDN博主「NeverSettle101」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/qq_21265915/article/details/104070710
Asp.Net Core中使用Swagger，你不得不踩的坑
aiamt68242?2018-07-08 13:23:00?
?933?
?收藏?1
版权
全能型容器服务的技术架构是什么样？亚马逊容器专家在线深度剖析并演示，马上预约！
很久不来写blog了，换了新工作后很累，很忙。每天常态化加班到21点，偶尔还会到凌晨，加班很累，但这段时间，也确实学到了不少知识，今天这篇文章和大家分享一下：Asp.Net Core中使用Swagger，你不得不踩的坑.
这篇文章着重讲几点：
- swagger 跨层注释问题
- swagger Get请求传多个参数的问题
- swagger Enum 注释问题
- swagger api文档版本控制
第一步：搭建一个webapi项目或者mvc项目，引入swagger nuget
我创建项目，习惯性的先创建一个解决方案，取名为TB.AspNetCore.Swagger
接着会在解决方案上新建项目，取名TB.AspNetCore.Swagger.SApi，然后选择webapi,https最好去掉，加上后提示你要证书什么的，还会提示你网站不安全，我们做测试，没必要勾选
为了本项目问题的说明，我们会继续在常见三个类库项目TB.AspNetCore.Swagger.Data 放数据库实体，TB.AspNetCore.Swagger.Model 放模型-ViewModel，TB.AspNetCore.Swagger.Enum 放枚举类型
?
删除项目默认生成的class和controller，在api项目上引入swagger的nuget包，搜索：Swashbuckle.AspNetCore，这个包就在持续更新速度很快，已经到了3.0
第二部：引入版本控制nuget，添加关键性配置代码
这两个包是做版本控制管理的，如果不需要可以不添加，这里我做演示就添加上，额外再引入一个包Microsoft.Extensions.PlatformAbstractions，这个包是获取一些系统配置路径变量的包，这个包实在鸡肋,没有注释。。添加部分关键代码在configuration和configurationservice，代码如下：
-
services.AddSwaggerGen( -
options => -
{ -
// resolve the IApiVersionDescriptionProvider service -
// note: that we have to build a temporary service provider here because one has not been created yet -
var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>(); -
// add a swagger document for each discovered API version -
// note: you might choose to skip or document deprecated API versions differently -
foreach (var description in provider.ApiVersionDescriptions) -
{ -
options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description)); -
} -
// add a custom operation filter which sets default values -
options.OperationFilter<SwaggerDefaultValues>(); -
// -
// integrate xml comments -
options.IncludeXmlComments(XmlCommentsFilePath); -
options.IncludeXmlComments(XmlModelsFilePath); -
}); -
public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider) -
{ -
if (env.IsDevelopment()) -
{ -
app.UseDeveloperExceptionPage(); -
} -
app.UseMvc(); -
//Swagger -
app.UseSwagger(); -
app.UseSwaggerUI( -
options => -
{ -
foreach (var description in provider.ApiVersionDescriptions) -
{ -
options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant()); -
} -
}); -
}
第三部：新建控制器，测试我们的项目
我做了一个订单查询控制器，一个提交订单，一个查询订单，查询订单为get请求多参数，提交订单为post请求，其中的备注设计到枚举类型的如何加载
代码如下：
namespace TB.AspNetCore.Swagger.SApi.Controllers
{
[Produces("application/json")]
[ApiVersion("1.0", Deprecated = false)]
[Route("api/v{api-version:apiVersion}/[controller]/[action]")]
[ApiController]
public class OrderController : ControllerBase
{
/// <summary>
/// 查询订单
/// </summary>
/// <param name="orderCode">订单号</param>
/// <param name="orderName">订单名称</param>
/// <returns></returns>
[HttpGet("{orderCode}/{orderName}")]
public OrderModel QueryOrder(string orderCode, string orderName)
{
OrderModel model = new OrderModel
{
OrderCode = orderCode
};
return model;
}
/// <summary>
/// 提交订单
/// </summary>
/// <param name="model"></param>
/// <returns></returns>
[HttpPost]
public OrderModel SubOrder([FromBody]OrderModel model)
{
return model;
}
}
public class OrderModel
{
/// <summary>
/// 订单号
/// </summary>
public string OrderCode { get; set; }
/// <summary>
/// 订单金额
/// </summary>
public decimal OrderAmount { get; set; }
/// <summary>
/// 订单类型
/// <Remark>
/// 0 商家入驻
/// 1 线下交易
/// </Remark>
/// </summary>
public OrderTypeInfo OrderType { get; set; }
}
/// <summary>
///
/// </summary>
public enum OrderTypeInfo
{
/// <summary>
/// 商家入驻
/// </summary>
[Description("商家入驻")]
StoreEntry = 0,
/// <summary>
/// 线下交易
/// </summary>
[Description("线下交易")]
StoreTrade = 1,
}
}
?效果图如下：**我把model和enum写到一个文件里，如果分别跨层写的话，也没有什么问题，只需要在startp里配置一下，由于时间关系，源码我上传到我都github，就不再细分了
?
