WebAPI帮助页面 – 返回或参数模型/类属性的文档

我正在使用Web API帮助页面与Web API 2（5.0） – 两个最新的Nuget包。 我想帮助文档显示属性的注释，这些类是参数或在HttpResponseMessage的主体中返回。

例如，我有一个像这样的控制器方法：

public HttpResponseMessage Post([FromBody] MyClassType1 myClass) { // Business logic removed for clarity return Request.CreateResponse(HttpStatusCode.OK, new MyClassType2()); } 

我希望MyClassType1和MyClassType2上的XML注释显示在上述post操作的帮助页面上。

我看过的所有地方，到目前为止看来还没有支持。 但是，我想知道是否有人能通过扩展ApiExplorer，添加到XmlDocumentationProvider等来实现这一点？

我知道注释和属性包含在生成的XML文件中，所以我可以尝试手动解析（所有参数和返回类型都在MyAssemblyName.Models命名空间中，所以我的想法是我可以查找XML具有以该命名空间开头的成员名称的节点。但是，我知道内置的Web API帮助页面具有一些缓存function，所以我更喜欢以某种方式将其与现有function相结合（只需添加它）。

我已经设法通过更新Parameters.cshtml模板来显示参数的类型（仅向下一层）：

 @using System.Reflection @using System.Threading @using System.Web.Http.Description @using Regency.API.Services.Areas.HelpPage @model System.Collections.ObjectModel.Collection  @foreach (ApiParameterDescription parameter in Model) { string parameterDocumentation = parameter.Documentation ?? "No documentation available."; Type parameterType = parameter.ParameterDescriptor.ParameterType; // Don't show CancellationToken because it's a special parameter if (!typeof (CancellationToken).IsAssignableFrom(parameter.ParameterDescriptor.ParameterType)) { 
 } } 
 
 
Name
Properties
Description
Additional information
 
 
 
@parameter.Name
 
 @foreach (PropertyInfo property in parameterType.GetProperties()) { @property.Name : @property.PropertyType.GetFriendlyTypeName() 
 } 
 
@parameterDocumentation

 @switch(parameter.Source) { case ApiParameterSource.FromBody: 

Define this parameter in the request body.
 break; case ApiParameterSource.FromUri: 
Define this parameter in the request URI.
 if (parameter.ParameterDescriptor.IsOptional) { 
This parameter is optional.
 } break; default: 
None.
 break; } 



 
 其中实现上面的GetFriendlyTypeName()方法如下所示： 如何使用reflection获得generics类型的正确文本定义？ 
 但是，这并没有让我得到这些类的注释，它对嵌套类型没有帮助（例如，如果我的模型上有一个复杂类型的属性，它就不会显示那个复杂类型属性的属性）。 如果没有他们的XML注释，这些类型就没用了。 
 此外，这仅适用于参数，但不适用于返回HttpResponseMessage正文中包含的类型。 我能够通过实现ResponseTypeAttribute来获取响应示例，如下所示： 自动生成的帮助页面，其返回类型为HttpResponseMessage，但同样没有给出带有XML注释的属性。 我可以使用reflection来获取类型，类似于我再次获取参数类型的方式，但我真的希望XML注释与类型一起，并包括嵌套的复杂类型。 
 我还发现将模型/类文档（带有类型和XML注释的属性）与服务调用分开记录是可以接受的，并且让服务调用只显示它们返回的类型的名称（然后至少用户可以找到该类型的文档）。 
 有没有人能够实现类似于我试图为参数或返回类型做的事情，最好是两者？ 还是有任何想法指出我正确的方向？ 


	







 
	
Answer 1
		      	
 记录复杂类型的各个属性的function目前正在开发中，可供下一版本使用。 那说你现在可以从Nightly版本中获取HelpPage包并尝试它。 您应该能够将此包升级到现有的5.0 web api项目。 
 目前，我们仅记录操作的输入类型，而不是通常用户想要了解输入类型信息的响应类型。 但是我可以看到用户可能也希望响应类型的信息也可以用于消费……我们将对此进行调查并告知您。 


Answer 2
		      	
 您可以进行修改以允许文档注释中的html 这是一个参考 。 
 在允许HTML之后，您可以将包含属性信息的表放在XML文档参数标记描述中。 您还可以查看帮助页面HTML源以获取用于帮助页面表的类属性名称，以便您的表将使用与所有其他表相同的CSS。 
 这是一个黑客但它的工作完美。