Swagger(ServiceStack)中未准确记录通用类型的响应对象

Question

关于泛型类型响应对象的文档,我遇到了Swagger的ServiceStack实现的问题.强类型响应对象被正确记录和显示,但是一旦使用泛型类型对象作为响应,文档就不准确并且会产生误导.

请求DTO

[Route("/users/{UserId}", "GET", Summary = "Get a specific User Profile")]
public class GetUser : IReturn<ServiceResponse<UserProfile>>
{
    [ApiMember(Description = "User Id", ParameterType = "path", IsRequired = true)]
    public int UserId { get; set; }
}

回复DTO

public class ServiceResponse<T> : IServiceResponse<T>
{
    public IList<string> Errors { get; set; }
    public bool Successful { get; set; }
    public string Message { get; set; }
    public string StackTrace { get; set; }
    public T Data { get; set; }

    public ServiceResponse()
    {
        Errors = new List<string>();
    }
}

响应DTO类型

public class UserProfile : RavenDocument
{
    public UserProfile()
    {
        Races = new List<UserRace>();
        Workouts = new List<Workout>();
    }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string DisplayName { get; set; }
    public DateTime? BirthDate { get; set; }
    public Gender? Gender { get; set; }
    public string UltracartPassword { get; set; }
    public string UltracartCartId { get; set; }

    [UniqueConstraint]
    public string Email { get; set; }

    public string ImageUrl { get; set; }

    public FacebookUserInfo FacebookData { get; set; }
    public GoogleUserInfo GoogleData { get; set; }

    public DateTime CreatedOn { get; set; }
    public DateTime? LastUpdated { get; set; }
    public UserAddress ShippingAddress { get; set; }
    public UserAddress BillingAddress { get; set; }
    public IList<UserRace> Races { get; set; }
    public IList<Workout> Workouts { get; set; }
}

这些例子很简单.没有什么是真正的hacky或聪明的事情,但这是我从Swagger开箱即用的示例文档:

如您所见,泛型类型未正确记录,而是使用其他类型.由于我正在使用相同的ServiceResponse包装器来处理所有响应,因此这种情况正在全面发生.

Answer 1

正如您所发现的，ServiceStack swagger 插件当前不会尝试干净地处理泛型类型。一个应该效果更好的简单替代方案是创建泛型类型的具体子类。例如：

public class UserProfileResponse : ServiceResponse<UserProfile> { ... }

public class GetUser : IReturn<UserProfileResponse> ...

这应该由 Swagger 妥善处理。

我发现泛型类型并不总是非常适合 ServiceStack DTO。您会在 StackOverflow 上找到许多讨论（例如此处、此处和此处），这些讨论都讨论了这一点，以及为什么具体类型和通常避免继承对于 ServiceStack DTO 来说是一个好主意的原因。

需要努力克服将 DRY 原则应用于请求/响应 DTO 的诱惑。我的想法是，泛型和继承是有助于以泛型、可重用方式实现算法的语言功能，其中泛型方法或基类不需要了解具体类型的细节。虽然 DTO 表面上可能具有看起来像继承或泛型机会的通用结构，但在这种情况下，每个 DTO 的实现和语义对于每个具体用途都是不同的，因此每个请求/响应消息的细节都需要明确定义。