我负责维护公司API文档。我们的API是用ASP.NET编写的。我最近改用了Swashbuckle 5.6.0,效果很好。
我遇到的问题是:
我们将数据模型分为发布数据和获取数据,例如WebAccountGetData.cs
和WebAccountPostData.cs
。创建(POST)和更新(PUT)时可以使用Post数据。
Post数据类中的大多数(如果不是全部)字段都可以为空,当调用API方法时,存储的proc返回错误消息,描述缺少/需要哪些字段。该API无法处理必填字段。
使用可为空的字段意味着Swashbuckle不会在文档中添加Required标志。但是,我们想根据所使用的Http方法(Post / Put)来显示是否需要一个字段。
API密钥是必需参数,因为它不能为空。
我知道我可以使用System.ComponentModel.DataAnnotations命名空间中的[Required]
属性,但这会将Required标志应用于我们不希望的POST和PUT方法。
理想地,我想使用一个自定义属性,在其中可以指定Post或Put方法中是否需要一个字段。
public class ApiRequiredAttribute : Attribute
{
public bool RequiredInPost
{
get;
set;
} = false;
public bool RequiredInPut
{
get;
set;
} = false;
}
然后像这样使用它:
[ApiRequired(RequiredInPost = true)]
public int? ApprovalStatusId
{
get;
set;
}
是否可以使用自定义IDocumentFilter
,IOperationFilter
或ISchemaFilter
将更改(如切换所需标志)应用于模型字段的架构属性?还是在Swashbuckle中无法引用模型上的属性?
答案 0 :(得分:0)
我设法找到了解决方案!
我创建了一个IOperationFilter
,它根据具有自定义ApiRequired
属性的属性(请参见原始问题)为POST和PUT方法创建新的模式。
internal class ApplyRequiredAttributeFilter : IOperationFilter
{
public void Apply( Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription )
{
HttpParameterBinding[] parameterBindings = apiDescription.ActionDescriptor.ActionBinding.ParameterBindings;
foreach ( HttpParameterBinding binding in parameterBindings ) {
PropertyInfo[] properties = binding.Descriptor.ParameterType.GetProperties();
// If the type is not an object and has no properties, ignore it.
if ( properties.Length == 0 ) {
continue;
}
Parameter modelParamater = operation.parameters.Last();
if ( modelParamater == null ) {
continue;
}
string schemaPath = modelParamater.schema?.@ref;
string schemaName = schemaPath?.Split( '/' ).Last();
if ( schemaName == null ) {
continue;
}
Schema oldSchema = schemaRegistry.Definitions[ schemaName ];
// Copy the existing schema.
Schema newSchema = new Schema
{
description = oldSchema.description,
properties = new Dictionary<string, Schema>( oldSchema.properties ),
required = oldSchema.required != null ? new List<string>( oldSchema.required ) : new List<string>(),
@type = oldSchema.type,
vendorExtensions = new Dictionary<string, object>( oldSchema.vendorExtensions )
};
// Find model properties with the custom attribute.
foreach ( PropertyInfo property in properties ) {
ApiRequiredAttribute attribute = property.GetCustomAttribute<ApiRequiredAttribute>();
if ( attribute != null ) {
// If the model property is required in POST/PUT and current HTTP method is POST/PUT
// Add the property to the new schema's required flags.
if ( attribute.RequiredInPut && apiDescription.HttpMethod.Method.Equals( "PUT" ) ||
attribute.RequiredInPost && apiDescription.HttpMethod.Method.Equals( "POST" ) ) {
newSchema.required.Add( property.Name );
string newSchemaName = $"{schemaName}:{apiDescription.HttpMethod.Method}";
if ( !schemaRegistry.Definitions.ContainsKey( newSchemaName ) ) {
schemaRegistry.Definitions.Add( newSchemaName, newSchema );
}
// Change the current model schema reference to the new schema with the addition required flags.
modelParamater.schema.@ref = $"{schemaPath}:{apiDescription.HttpMethod.Method}";
}
}
}
}
}
}
然后将过滤器添加到EnableSwagger调用中。
GlobalConfiguration.Configuration
.EnableSwagger("docs/swagger/", c =>
{
// Other initialization code...
c.OperationFilter<ApplyRequiredAttributeFilter>();
});
属性的使用方式如下:
[ApiRequired( RequiredInPost = true, RequiredInPut = true)]
public bool? Active
{
get;
set;
}
[ApiRequired( RequiredInPost = true )]
public string UserName
{
get;
set;
}
最后,在文档上,所需的标志如下所示。 POST方法参数在左侧,而PUT方法参数在右侧: