目录
[1. 创建自定义Schema过滤器](#1. 创建自定义Schema过滤器)
[2. 注册自定义Schema过滤器](#2. 注册自定义Schema过滤器)
[3. 配置具体的属性或类型（可选）](#3. 配置具体的属性或类型（可选）)
[4. 运行并查看结果](#4. 运行并查看结果)
如果您喜欢此文章，请收藏、点赞、评论，谢谢，祝您快乐每一天。
在使用Swagger（特别是通过Swashbuckle库在.NET Core/ASP.NET Core项目中）时，我们经常需要为模型的属性提供示例值或描述，以便更好地展示API文档。这可以通过实现ISchemaFilter接口来完成，该接口允许我们在Swagger生成过程中自定义模型属性。
以下是如何实现ISchemaFilter接口来注入示例值和描述的步骤：
1. 创建自定义Schema过滤器
首先，创建一个类来实现ISchemaFilter接口。在这个类中，你可以定义如何修改模型的Schema。
using Swashbuckle.AspNetCore.SwaggerGen;
using Microsoft.OpenApi.Models;
using System.Collections.Generic;
using System.Linq;
public class ExampleSchemaFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
// 你可以在这里添加逻辑来设置默认的示例值和描述
// 比如，为所有字符串类型的属性添加示例值和描述
if (context.Type == typeof(string))
{
schema.Example = "示例字符串"; // 设置示例值
schema.Description = "这是一个示例字符串描述"; // 设置描述
}
// 你可以根据需要为其他类型或属性设置示例值和描述
}
}
2. 注册自定义Schema过滤器
在Startup.cs或Program.cs文件中注册你的自定义Schema过滤器。确保在添加Swagger服务时加入你的过滤器。
对于Startup.cs (ASP.NET Core 3.x 或更早版本)
public void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerGen(c =>
{
c.SchemaFilter<ExampleSchemaFilter>(); // 注册自定义Schema过滤器
});
}
对于Program.cs (ASP.NET Core 5.x 或更新版本)
builder.Services.AddSwaggerGen(c =>
{
c.SchemaFilter<ExampleSchemaFilter>(); // 注册自定义Schema过滤器
});
3. 配置具体的属性或类型（可选）
如果你想为特定的属性或类型设置示例值和描述，可以在Apply方法中添加条件判断。例如，只对某个特定类型或属性名设置：
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
if (context.Type == typeof(MyCustomType)) // 针对特定类型
{
schema.Example = new MyCustomType { /* 设置示例值 */ }; // 设置示例对象
schema.Description = "这是一个自定义类型的描述"; // 设置描述
}
else if (context.PropertyName == "SpecificProperty") // 针对特定属性名
{
schema.Example = "特定属性的示例值"; // 设置示例值
schema.Description = "这是一个特定属性的描述"; // 设置描述
}
}
4. 运行并查看结果
运行你的应用程序并访问Swagger UI，你应该能看到模型属性上的示例值和描述。这有助于API消费者更好地理解如何使用你的API。
通过上述步骤，你可以灵活地为你的Swagger文档中的模型属性添加示例值和描述，从而提高API文档的可用性和易用性。
如果您喜欢此文章，请收藏、点赞、评论，谢谢，祝您快乐每一天。