webapi返回html页面,c# – 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注释显示在上述帖子操作的帮助页面上.

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

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

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

@using System.Reflection

@using System.Threading

@using System.Web.Http.Description

@using Regency.API.Services.Areas.HelpPage

@model System.Collections.ObjectModel.Collection

NamePropertiesDescriptionAdditional information

@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))

{

@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;

}

}

}

但是,这并没有让我得到这些类的注释,它对嵌套类型没有帮助(例如,如果我的模型上有一个复杂类型的属性,它就不会显示该复杂类型属性的属性).如果没有他们的XML注释,这些类型就没用了.

此外,这仅适用于参数,但不适用于返回HttpResponseMessage正文中包含的类型.我能够通过实现ResponseTypeAttribute来获取响应示例,如下所示：Auto generated help pages with return type HttpResponseMessage但是再次没有给出带有XML注释的属性.我可以使用反射来获取类型,类似于我再次获取参数类型的方式,但我真的希望XML注释与类型一起使用,并包括嵌套的复杂类型.

我还发现将模型/类文档(带有类型和XML注释的属性)与服务调用分开记录是可以接受的,并且让服务调用只显示它们返回的类型的名称(然后至少用户可以找到该类型的文档).

有没有人能够实现类似于我试图为参数或返回类型做的事情,最好是两者兼而有之？还是有任何想法指出我正确的方向？

解决方法:

记录复杂类型的各个属性的功能目前正在开发中,可供下一版本使用.那说你现在可以从Nightly版本中获取HelpPage包并尝试它.您应该能够将此包升级到现有的5.0 Web api项目.

目前,我们仅记录操作的输入类型,而不是通常用户想要了解输入类型信息的响应类型.但我可以看到用户可能也希望响应类型的信息也可以用于消费……我们将调查此信息并告知您.