如何使用 Servicestack swagger-api (1.2) 在 ServiceStack 中记录服务响应答案

【问题标题】：How do document service responses in ServiceStack with Servicestack swagger-api (1.2)如何使用 Servicestack swagger-api (1.2) 在 ServiceStack 中记录服务响应
【发布时间】：2017-02-02 08:54:09
【问题描述】：

我正在使用swagger ui 作为我的 ServiceStack 网络服务的文档，它工作得非常好。但是，我没有找到一种方法来添加有关这些 Web 服务（json）响应的任何信息。所以当我的服务的GET 方法看起来像这样时：

    public object Get(CustomerData customers)
    {
         List<CustomerDAO> customers = DataProvider.GetAllCustomers();
         return customers;
    }


 public class CustomerDAO
 {
     // this is important information which needs to be visible in swagger-ui
    public string Name { get; set; }
    public string SomeImportantProperty { get; set; }    
    public string AnotherPropery { get; set; }
    public string AlsoWorthDocumenting { get; set; }
    // and so on...
  }

我需要对文档 (swagger-ui) 中的每个属性进行简短描述，这对于使用这些 Web 服务至关重要。

我使用的是 ServiceStack 3.9.74，但这也应该适用于最新的 ServiceStack 版本。如果没有，请告诉我。

我想知道如何才能大摇大摆地获得这些信息，或者如果没有，如何将如此重要的信息提供给必须使用我的 Web 服务的开发人员。我也愿意接受任何其他适用于 ServiceStack 环境的方法或最佳实践。

【问题讨论】：

@stout01 的回答是正确的，还强烈建议您遵循建议始终为您的服务创建专用响应对象。更好的是，尽量不要暴露你的 ORM（OrmLite？）使用的类型，因为它会在你的数据访问和你的 API 之间创建一个紧密的耦合，现在你的 API 的客户端暴露了。这使得您很难在不破坏 API 合同和客户端的情况下更改数据库模型。还应创建另一个表示Customer 的类型。

标签： c# rest servicestack swagger

【解决方案1】：

我不确定您的 ServiceStack 版本。在最新版本中，您将请求 dto inheirt IReturn<ReturnClassHere>，这将告诉 swagger 查看该返回类。

所以您的 CustomerData 类看起来像这样：

public class CustomerData : IReturn<List<CustomerDAO>>
{
}

虽然为您的响应设置另一个 dto 可能会更好，该响应将被返回。也许像CustomerDataResponse。

【讨论】：

不幸的是，这在 1.2 中不起作用。我还在响应的属性中添加了ApiMember 属性，但是swagger 不接。我猜这个功能不是 1.2 的一部分。