servicestack - 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 上找到许多讨论(例如 here 、 here 和 here )讨论这个问题，以及为什么具体类型和通常避免继承对于 ServiceStack DTO 是一个好主意的原因。

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