.NET Core 6 API中向Swagger Schema添加非内联现有模型及Webhook模型

一、直接添加现有未使用的错误模型到Swagger Schema #

无需内联定义，通过Swashbuckle的配置即可直接注册未被API端点引用的模型：

1. 在Program.cs的Swagger配置块中，使用IncludeTypes方法指定要纳入Schema的模型：

builder.Services.AddSwaggerGen(options =>
{
    // 注册网关返回的错误模型
    options.IncludeTypes(typeof(GatewayErrorModel));
    options.IncludeTypes(typeof(GatewayValidationErrorModel));
});

执行后，指定的模型会被Swagger自动扫描并生成对应的Schema，加入到文档的components/schemas节点中。

2. （可选）为模型添加自定义描述和示例
   如果需要给模型补充描述或示例数据，可以实现自定义ISchemaFilter：

public class ErrorModelSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(GatewayErrorModel))
        {
            schema.Description = "网关处理请求时返回的通用错误模型";
            // 设置示例数据
            schema.Example = new OpenApiObject
            {
                ["errorCode"] = new OpenApiString("GW-500"),
                ["errorMessage"] = new OpenApiString("网关内部错误"),
                ["requestId"] = new OpenApiString("abc123xyz")
            };
        }
    }
}

然后在Swagger配置中注册该过滤器：

builder.Services.AddSwaggerGen(options =>
{
    options.IncludeTypes(typeof(GatewayErrorModel));
    options.SchemaFilter<ErrorModelSchemaFilter>();
});

二、添加Webhook模型及示例到Schema集合 #

同样使用IncludeTypes注册Webhook相关模型，再通过SchemaFilter补充示例信息：

1. 注册Webhook模型

builder.Services.AddSwaggerGen(options =>
{
    options.IncludeTypes(typeof(WebhookNotificationModel));
    options.IncludeTypes(typeof(WebhookEventModel));
});

2. 为Webhook模型添加示例和描述
   创建对应的SchemaFilter：

public class WebhookModelSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(WebhookNotificationModel))
        {
            schema.Description = "Webhook推送的通知模型";
            schema.Example = new OpenApiObject
            {
                ["eventType"] = new OpenApiString("OrderCreated"),
                ["eventTime"] = new OpenApiString(DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ")),
                ["payload"] = new OpenApiObject
                {
                    ["orderId"] = new OpenApiString("ORD-10001"),
                    ["totalAmount"] = new OpenApiDouble(99.99)
                }
            };
        }
    }
}

注册过滤器：

builder.Services.AddSwaggerGen(options =>
{
    options.IncludeTypes(typeof(WebhookNotificationModel));
    options.SchemaFilter<WebhookModelSchemaFilter>();
});

补充：结合XML注释增强模型文档 #

如果项目已启用XML文档，可以让Swagger自动读取模型的注释：

1. 右键项目 → 属性 → 生成 → 勾选"XML文档文件"，设置输出路径。
2. 在Swagger配置中引入XML文件：

var xmlDocPath = Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml");
options.IncludeXmlComments(xmlDocPath, includeControllerXmlComments: true);

这样模型的注释会自动同步到Swagger文档中，无需手动编写描述。

内容的提问来源于stack exchange，提问作者streamingpro