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

Question

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

以下面的屏幕截图为例。

这是通过用户ID GET用户的终结点，并且在Resource Description部分中，它显示了一个表，该表显示了用户模型的属性，因为我的控制器操作具有[ResponseType(typeof(User))]批注。

首先，在我实际的控制器操作中，在不向Password显示结果之前，我先删除了Password属性，以免泄露敏感信息。 因此，“ Resource Description部分中给出的表是错误的，也就是说我的API返回的字段不是。

其次，在“ Additional Information列下，它显示了与User模型一起使用的验证规则。 方便，但不是在，因为这端点此情况下，所有相关的GET荷兰国际集团用户，不POST荷兰国际集团之一。

因此，我的问题是如何自定义此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文件中读取文档，该XML文件是在我构建项目时从这些///注释中构建的。

谢谢！

Answer 1

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

现在，您正在使用数据模型作为视图模型。

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

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

您遇到了＃1和＃2的原因。

您的解决方案应该是：

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