c# - 自定义 ASP.NET Web API 帮助页面的 "Resource Description"部分

Question

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

以下面的截图为例。

这是一个通过 ID GET 用户的端点，在 Resource Description 部分，它显示了一个表，该表显示了用户模型的属性，因为我的 Controller 操作有[ResponseType(typeof(User))] 注释。

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

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

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

我目前这样评论我的 Controller 操作:

/// <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 应用程序中， View 模型是从 Controller 返回到 View 引擎的模型。在 Web API 应用程序中， View 模型是暴露给 API 使用者的模型。

就目前而言，您正在使用数据模型作为 View 模型。

将 View 模型与数据模型分开的原因有很多:

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

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

你的解决方案应该是:

1. 创建一个新类作为您的 View 模型。现在，您有一个 User 数据模型类。创建一个 UserViewModel 类(随便命名)。
2. 向应向用户公开的此类添加成员。不要在您的案例中包含 Password。
3. 添加适合在自动生成的帮助中看到的注释。
4. 将数据从 User 类复制到 UserViewModel 类，并从您的 Controller 返回 UserViewModel 类。