的WebAPI帮助页面 - 文档进行退货或参数模型/类的属性 [英] WebAPI Help Page - Documentation for return or parameter model/class properties

问题描述

我使用的Web API帮助页面使用Web API 2（5.0） - 无论是最新的NuGet包。我想帮助文档上显示的是参数或在身体恢复类的属性意见的Htt presponseMessage。

I am using Web API Help Page with Web API 2 (5.0) - both the latest Nuget packages. I would like the help documentation to show the comments of the properties on classes that are parameters or returned in the body of the HttpResponseMessage.

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

For example, I have a controller method like this:

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

我想，我对XML注释 MyClassType1 和 MyClassType2 上要显示帮助页面上述职位的行动。

I would like the XML comments that I have on MyClassType1 and MyClassType2 to be displayed on the help page for the above post action.

无论我已经看过，到目前为止，它看来，这尚不支持。不过，我想知道是否有人已经能够获得通过扩展ApiExplorer工作，增加XmlDocumentationProvider等？

Everywhere I have looked, so far it appears that this is not yet supported. However, I am wondering if anyone has been able to get this to work by extending ApiExplorer, adding to XmlDocumentationProvider, etc?

我知道了意见和属性包括获取生成的XML文件中，这样我就可以尝试手动解析（所有参数和返回类型都在 MyAssemblyName.Models 命名空间，所以我的想法是，我可以寻找那​​些有成员的名字开始与命名空间中的XML节点。但是，我知道了内置的Web API帮助页面有一些缓存功能，所以我preFER与现有的功能（只需加给它）以某种方式合并此。

I know that the comments and properties are included in the XML file that gets generated, so I could try to parse that manually (all the parameter and return types are in the MyAssemblyName.Models namespace, so my thought was I could look for the XML nodes that have a member name starting with that namespace. However, I know the built-in web API help pages have some caching features, so I prefer to somehow incorporate this with the existing functionality (just add on to it).

我已成功地显示参数类型（一层仅下跌）通过更新Parameters.cshtml模板是：

I have managed to show the types of the parameters (one layer down only) by updating the Parameters.cshtml template to this:

@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（）上面的方法来实现，如下所示：<一href=\"http://stackoverflow.com/questions/401681/how-can-i-get-the-correct-text-definition-of-a-generic-type-using-reflection/401824#401824\">How我可以使用反射泛型类型的正确的文本定义？

where the GetFriendlyTypeName() method above is implemented as shown here: How can I get the correct text definition of a generic type using reflection?

不过，这并没有让我从这些类的评论，它不与嵌套类型帮助（例如，如果我的模型对其有一个复杂类型属性，它不会显示的那么复杂类型的属性属性）。而且种类还不够有用没有他们的XML注释反正。

However, this doesn't get me the comments from these classes and it doesn't help with nested types (e.g. if my model had a complex-typed property on it, it would not show the properties of that complex-typed property). And the types are not useful enough without their XML comments anyway.

另外，这仅适用于参数，但不返回包含在Htt的presponseMessage的主体类型。我能得到的回应样品通过实施 ResponseTypeAttribute 如下所示工作：<一href=\"http://stackoverflow.com/questions/17821088/auto-generated-help-pages-with-return-type-htt$p$psponsemessage/17822786#17822786\">Auto生成的帮助页面，返回类型的Htt presponseMessage 却又不给我用XML注释的属性。我可以使用反射来获得同样的类型我得到了再次的参数类型，但我真的想与类型类似于XML注释在一起，包括嵌套的复杂类型。

Also, this only applies to parameters, but not to return types contained in the body of the HttpResponseMessage. I was able to get the response samples to work by implementing a ResponseTypeAttribute as shown here: Auto generated help pages with return type HttpResponseMessage but again that doesn't give me the properties with XML comments. I could use reflection to get the types similarly to how I got the parameter types again, but I really would like the XML comments together with types, and including nested complex types.

我也觉得可以接受的记录模式/类文档（具有类型和XML注释属性）分别从服务电话，有服务调用只显示类型的，他们返回（当时至少名称用户可以找到该类型的文档）。

I would also find it acceptable to document the model/class documentation (properties with types and XML comments) separately from the service calls, and have the service calls just show the name of the type that they return (then at least the user could find the documentation for that type).

任何人都已经能够实现类似的东西是什么，我想对于任何一个参数做或返回类型，preferably两者兼而有之？或者有什么想法，我指出了正确的方向？

Has anyone been able to implement something similar to what I am trying to do for either parameters or return types, preferably both? Or any ideas to point me in the right direction?

推荐答案

记录复杂类型的个别属性的功能目前正在开发和将可用于下一个版本。这就是说，你现在可以得到HelpPage包从每日构建和尝试。您应该能够对这个包升级到现有的5.0的Web API项目。

The feature of documenting individual properties of a complex type is currently in development and would be available for next release. That said you can currently get the HelpPage package from the Nightly builds and try it. You should be able to upgrade this package onto an existing 5.0 web api project.

也是目前我们只记录了行动的输入类型，而不是反应类型，一般用户会想知道的输入类型的信息。但我可以看到用户可能要用于消费的响应类型的信息太...我们将看看这个，将让你知道。

Also currently we document only the action's input types and not the response types as generally users would want to know about the input types's information. But I can see that users might want the response type's information for consumption too...we will look into this and will let you know.

这篇关于的WebAPI帮助页面 - 文档进行退货或参数模型/类的属性的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！