如何在Swagger.Net的SwaggerExample特性中传入复杂自定义对象？

核心限制说明 #

.NET 特性的构造参数仅支持传入编译时常量（字符串、基础值类型、typeof表达式等），无法直接传入自定义类的运行时实例，所以不能直接把预定义的Thing对象塞进SwaggerExample的参数里。

可用解决方案 #

方案1：直接传入序列化后的JSON字符串 #

把你预定义的Thing实例手动序列化为JSON字符串，直接传入SwaggerExample特性即可，Swagger.Net会自动把JSON字符串解析为对应复杂类型的示例展示。
示例代码：

[Route("SaveCustomThing"), HttpPost]
[SwaggerExample("thing", "{\"Id\":1,\"Name\":\"自定义物品\",\"Status\":1,\"ExtInfo\":{\"Tag\":\"测试\",\"Remark\":\"示例备注\"}}")]
public HttpResponseMessage SaveCustomThing([FromBody] Thing thing)
{...}

注意：JSON结构要和Thing类的属性结构完全匹配，避免出现示例展示格式错误。

方案2：自定义特性实现可复用的示例配置 #

如果不想硬编码JSON，需要统一维护多个接口的示例数据，可以自定义继承自SwaggerExampleAttribute的扩展特性，通过静态工厂生成示例对象再自动序列化。

第一步：定义示例工厂类，统一维护所有接口的示例数据

public static class SwaggerExampleFactory
{
    // 定义Thing类型的示例生成方法
    public static Thing GetThingExample()
    {
        return new Thing
        {
            Id = 1,
            Name = "自定义物品",
            Status = 1,
            ExtInfo = new ThingExtInfo
            {
                Tag = "测试",
                Remark = "示例备注"
            }
        };
    }

    // 其他类型的示例方法可继续往下加
}

第二步：定义扩展的Swagger复杂示例特性

using Newtonsoft.Json;
using Swagger.Net.Annotations;
using System.Reflection;

public class SwaggerComplexExampleAttribute : SwaggerExampleAttribute
{
    public SwaggerComplexExampleAttribute(string paramName, Type exampleProviderType, string exampleMethodName)
        : base(paramName, GenerateExampleJson(exampleProviderType, exampleMethodName))
    {
    }

    private static string GenerateExampleJson(Type providerType, string methodName)
    {
        // 从静态工厂类中获取示例生成方法
        MethodInfo method = providerType.GetMethod(methodName, BindingFlags.Public | BindingFlags.Static);
        if (method == null)
        {
            throw new ArgumentException($"未在{providerType.Name}中找到公开静态方法{methodName}");
        }
        // 执行方法拿到示例对象，序列化为JSON
        object exampleInstance = method.Invoke(null, null);
        return JsonConvert.SerializeObject(exampleInstance);
    }
}

第三步：在接口上使用自定义特性

[Route("SaveCustomThing"), HttpPost]
[SwaggerComplexExample("thing", typeof(SwaggerExampleFactory), nameof(SwaggerExampleFactory.GetThingExample))]
public HttpResponseMessage SaveCustomThing([FromBody] Thing thing)
{...}

这种方案的优势是所有示例数据统一维护，修改的时候只需要改工厂类里的对应方法即可，不需要逐个修改接口特性里的硬编码JSON。

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