自定义＆＃34;资源描述＆＃34; ASP.NET Web API帮助页面的一部分

Question

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

以下面的屏幕截图为例。

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

首先，在我的实际控制器操作中，我在向用户显示结果之前剥离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文件中读取文档，该文件是在构建项目时根据这些///注释构建的。

谢谢！

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类（根据需要命名）。
2. 向此类添加应向用户公开的成员。不要在您的案例中包含Password。
3. 添加适合在自动生成的帮助中看到的注释。
4. 将数据从User类复制到UserViewModel类，并从控制器返回UserViewModel类。