4

我正在使用带有 Web API 2 (5.0) 的 Web API 帮助页面——这两个都是最新的 Nuget 包。我希望帮助文档显示对作为参数或在 HttpResponseMessage 正文中返回的类的属性的注释。

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

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

我希望我拥有的 XML 评论MyClassType1显示MyClassType2在上述发布操作的帮助页面上。

我看过的所有地方，到目前为止似乎还不支持。但是，我想知道是否有人能够通过扩展 ApiExplorer、添加到 XmlDocumentationProvider 等来使其工作？

我知道注释和属性包含在生成的 XML 文件中，所以我可以尝试手动解析（所有参数和返回类型都在MyAssemblyName.Models命名空间中，所以我的想法是我可以查找具有一个以该命名空间开头的成员名称。但是，我知道内置的 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<ApiParameterDescription>

<table class="help-page-table">
    <thead>
        <tr><th>Name</th><th>Properties</th><th>Description</th><th>Additional information</th></tr>
    </thead>
    <tbody>
        @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))
            {
                <tr>
                    <td class="parameter-name"><b>@parameter.Name</b></td>
                    <td class="parameter-properties">
                        @foreach (PropertyInfo property in parameterType.GetProperties())
                        {
                            <text>@property.Name : @property.PropertyType.GetFriendlyTypeName()</text>
                            <br/>
                        }
                    </td>
                    <td class="parameter-documentation"><pre>@parameterDocumentation</pre></td>
                    <td class="parameter-source">
                        @switch(parameter.Source)
                        {
                            case ApiParameterSource.FromBody:
                                <p>Define this parameter in the request <b>body</b>.</p>
                                break;
                            case ApiParameterSource.FromUri:
                                <p>Define this parameter in the request <b>URI</b>.</p>
                                if (parameter.ParameterDescriptor.IsOptional)
                                {
                                    <p>This parameter is <b>optional</b>.</p>
                                }
                                break;
                            default:
                                <p>None.</p>
                                break;
                        }
                    </td>
                </tr>
            }
        }
    </tbody>
</table>

上述GetFriendlyTypeName()方法的实现如下所示：如何使用反射获得泛型类型的正确文本定义？

但是，这并没有让我得到这些类的注释，并且它对嵌套类型没有帮助（例如，如果我的模型上有一个复杂类型的属性，它将不会显示该复杂类型属性的属性）。无论如何，如果没有 XML 注释，这些类型就不够用了。

此外，这仅适用于参数，但不适用于 HttpResponseMessage 正文中包含的返回类型。ResponseTypeAttribute通过实现如下所示，我能够使响应示例正常工作：自动生成返回类型为 HttpResponseMessage 的帮助页面，但同样没有为我提供带有 XML 注释的属性。我可以使用反射来获取类型，类似于我再次获取参数类型的方式，但我真的希望 XML 注释与类型一起，包括嵌套的复杂类型。

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

有没有人能够实现类似于我试图为参数或返回类型做的事情，最好是两者？或者有什么想法可以为我指明正确的方向？

4

2 回答 2

5

记录复杂类型的单个属性的功能目前正在开发中，并将在下一个版本中可用。也就是说，您目前可以从 Nightly 构建中获取 HelpPage 包并进行尝试。您应该能够将此包升级到现有的 5.0 web api 项目。

此外，目前我们仅记录操作的输入类型而不是响应类型，因为通常用户希望了解输入类型的信息。但我可以看到，用户可能也希望响应类型的信息用于消费......我们将对此进行调查并通知您。

于 2013-10-28T23:43:25.063 回答
0

您可以进行修改以允许在文档注释中使用 html Here is a Reference。

允许 HTML 后，您可以在 XML 文档参数标记描述所在的位置放置一个包含属性信息的表格。您还可以查看帮助页面 HTML 源以获取用于帮助页面表格的类属性名称，以便您的表格将使用与所有其他表格相同的 CSS。

这是一个 hack，但它工作得很好。

于 2015-02-19T16:07:38.497 回答