自定义 ASP.NET Web API 帮助页面的 "Resource Description" 部分
Customizing the "Resource Description" section of a ASP.NET Web API help page
我正在使用 ASP.NET Web API，它可以方便地自动为我的 API 生成文档，但其中一些没有意义。
以下面的截图为例
这是 GET 用户 ID 的端点，在 Resource Description 部分显示了 table，它显示了用户模型的属性，因为我的控制器操作具有[ResponseType(typeof(User))] 注释。
首先，在我的实际控制器操作中，我在向用户显示结果之前删除了 Password 属性，以免泄露敏感信息。所以 Resource Description 部分中给出的 table 是不正确的，它说我的 API returns 字段不正确。
其次，在 Additional Information 列下，它显示了与 User 模型一起使用的验证规则。方便，但在这种情况下根本不相关，因为此端点用于 GETing 用户，而不是 POSTing 用户。
所以，我的问题是如何自定义此 Resource Description table 以指定自己返回哪些字段，并隐藏 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 文件中读取文档，该文件是在我构建项目时根据这些 /// 评论构建的。
谢谢！
在传统的 MVC 应用程序中，视图模型是从控制器 return 到视图引擎的模型。在 Web API 应用程序中，视图模型是暴露给 API 消费者的模型。
就像现在一样，您正在使用数据模型作为视图模型。
将视图模型与数据模型分开的原因有很多：
- 安全：确保敏感数据（如密码）不会意外暴露
- Web API 界面和数据库数据之间的数据差异（例如，Web API 界面中的
enum 与数据库中的 int）。
- 帮助确保网络 API 界面保持一致，即使内部数据结构发生变化。
- 允许您区分
GET 和 POST 方法之间的数据。例如，某些数据可能在 POSTing 时确定，例如记录创建日期。该数据可以从 GET 中 return 编辑，但您不希望它包含在 POST. 中
您已经找到原因 #1 和 #2。
您的解决方案应该是：
- 创建一个新的 class 作为您的视图模型。现在，您有一个
User 数据模型 class。创建一个 UserViewModel class （随便命名）。
- 向此 class 添加应该向用户公开的成员。不要在您的案例中包含
Password。
- 添加适合在自动生成的帮助中看到的注释。
- 复制数据从
Userclass到UserViewModelclass和return从UserViewModelclass你的控制器。
我正在使用 ASP.NET Web API，它可以方便地自动为我的 API 生成文档，但其中一些没有意义。
以下面的截图为例
这是 GET 用户 ID 的端点，在 Resource Description 部分显示了 table，它显示了用户模型的属性，因为我的控制器操作具有[ResponseType(typeof(User))] 注释。
首先，在我的实际控制器操作中，我在向用户显示结果之前删除了 Password 属性，以免泄露敏感信息。所以 Resource Description 部分中给出的 table 是不正确的，它说我的 API returns 字段不正确。
其次，在 Additional Information 列下，它显示了与 User 模型一起使用的验证规则。方便，但在这种情况下根本不相关，因为此端点用于 GETing 用户，而不是 POSTing 用户。
所以，我的问题是如何自定义此 Resource Description table 以指定自己返回哪些字段，并隐藏 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 文件中读取文档，该文件是在我构建项目时根据这些 /// 评论构建的。
谢谢！
在传统的 MVC 应用程序中，视图模型是从控制器 return 到视图引擎的模型。在 Web API 应用程序中，视图模型是暴露给 API 消费者的模型。
就像现在一样，您正在使用数据模型作为视图模型。
将视图模型与数据模型分开的原因有很多：
- 安全：确保敏感数据（如密码）不会意外暴露
- Web API 界面和数据库数据之间的数据差异（例如，Web API 界面中的
enum与数据库中的int）。 - 帮助确保网络 API 界面保持一致，即使内部数据结构发生变化。
- 允许您区分
GET和POST方法之间的数据。例如，某些数据可能在POSTing 时确定，例如记录创建日期。该数据可以从GET中 return 编辑，但您不希望它包含在POST. 中
您已经找到原因 #1 和 #2。
您的解决方案应该是：
- 创建一个新的 class 作为您的视图模型。现在，您有一个
User数据模型 class。创建一个UserViewModelclass （随便命名）。 - 向此 class 添加应该向用户公开的成员。不要在您的案例中包含
Password。 - 添加适合在自动生成的帮助中看到的注释。
- 复制数据从
Userclass到UserViewModelclass和return从UserViewModelclass你的控制器。