自定义 ASP.NET Web API 帮助页面的“资源描述”部分

Question

我正在使用 ASP.NET Web API，它可以方便地自动为我的 API 生成文档，但其中一些没有意义。

以下面的截图为例。

这是GET 用户 ID 的端点，在 Resource Description 部分它显示了一个表格，其中显示了用户模型的属性，因为我的控制器操作具有 [ResponseType(typeof(User))] 注释。

首先，在我的实际控制器操作中，我在向用户显示结果之前剥离了Password 属性，以免暴露敏感信息。所以Resource Description 部分中给出的表格是不正确的，它说我的 API 返回了它没有返回的字段。

其次，在Additional Information 列下，它显示了与User 模型一起使用的验证规则。方便，但在这种情况下根本不相关，因为此端点用于 GETing 用户，而不是 POSTing 用户。

所以，我的问题是如何自定义此 Resource Description 表以指定自己返回哪些字段并隐藏 EF 验证？

我目前这样评论我的控制器操作：

/// <summary>
/// Get a single user identified by ID.
/// </summary>
/// <param name="userId">The ID of the user.</param>
/// <returns>A data collection about the user.</returns>
[ResponseType(typeof(User))]
[Route("api/v1/users/{userId}", Name="GetUser")]
[HttpGet]
public IHttpActionResult GetUser(int userId)
{
    // ...
}

并且我已将帮助页面配置为从 XML 文件中读取文档，该文件是在我构建项目时从这些 /// cmets 构建的。

谢谢！

Answer 1

在传统的 MVC 应用程序中，视图模型是从控制器返回到视图引擎的模型。在 Web API 应用程序中，视图模型是向 API 使用者公开的模型。

就像现在一样，您将数据模型用作视图模型。

将视图模型与数据模型分开的原因有很多：

1. 安全性：确保敏感数据（如密码）不会意外泄露
2. Web API 接口与数据库数据之间的数据差异（例如，Web API 接口中的enum 与数据库中的int）。
3. 即使内部数据结构发生变化，也有助于确保 Web API 界面保持一致。
4. 允许您区分 GET 和 POST 方法之间的数据。例如，可能某些数据是在POSTing 时确定的，例如记录创建日期。该数据可以从GET 返回，但您不希望它包含在POST 中。

您已经找到了原因 #1 和 #2。

您的解决方案应该是：

1. 创建一个新类作为您的视图模型。现在，您有一个User 数据模型类。创建一个UserViewModel 类（随意命名）。
2. 向该类添加应向用户公开的成员。不要在您的情况下包含Password。
3. 添加适合在自动生成的帮助中看到的注释。
4. 将数据从User 类复制到UserViewModel 类并从控制器返回UserViewModel 类。