Estou usando a página de Ajuda da API da Web com a Web API 2 (5.0) - ambos os pacotes Nuget mais recentes. Eu gostaria que a documentação de ajuda mostrasse os comentários das propriedades em classes que são parâmetros ou retornadas no corpo do HttpResponseMessage.

Por exemplo, eu tenho um método de controle como este:

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

Eu gostaria que os comentários XML que tenho sobreMyClassType1 eMyClassType2 para ser exibido na página de ajuda para a ação de postagem acima.

Em todos os lugares que eu olhei, até agora parece que isso ainda não é suportado. No entanto, estou querendo saber se alguém conseguiu fazer isso funcionar estendendo o ApiExplorer, adicionando ao XmlDocumentationProvider, etc?

Eu sei que os comentários e propriedades estão incluídos no arquivo XML que é gerado, então eu poderia tentar analisar isso manualmente (todos os tipos de parâmetro e retorno estão noMyAssemblyName.Models namespace, então pensei em procurar os nós XML que têm um nome de membro começando com esse namespace. No entanto, sei que as páginas de ajuda da API da Web incorporadas têm alguns recursos de armazenamento em cache, portanto, prefiro incorporar isso de alguma forma à funcionalidade existente (basta adicionar a ela).

Eu consegui mostrar os tipos de parâmetros (apenas uma camada abaixo) atualizando o modelo Parameters.cshtml para isto:

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

onde oGetFriendlyTypeName() método acima é implementado como mostrado aqui:Como posso obter a definição de texto correta de um tipo genérico usando reflexão?

No entanto, isso não me traz os comentários dessas classes e não ajuda com os tipos aninhados (por exemplo, se meu modelo tivesse uma propriedade de tipo complexo, não mostraria as propriedades dessa propriedade de tipo complexo). E os tipos não são úteis o suficiente sem seus comentários XML de qualquer maneira.

Além disso, isso se aplica apenas aos parâmetros, mas não para retornar tipos contidos no corpo do HttpResponseMessage. Consegui que as amostras de resposta funcionassem implementando umaResponseTypeAttribute como mostrado aqui:Páginas de ajuda geradas automaticamente com o tipo de retorno HttpResponseMessage mas mais uma vez isso não me dá as propriedades com comentários XML. Eu poderia usar a reflexão para obter os tipos de forma semelhante a como eu tenho os tipos de parâmetro novamente, mas eu realmente gostaria de comentários XML junto com tipos e incluindo tipos complexos aninhados.

Eu também consideraria aceitável documentar a documentação do modelo / classe (propriedades com tipos e comentários XML) separadamente das chamadas de serviço, e fazer as chamadas de serviço apenas mostrar o nome do tipo que elas retornam (pelo menos o usuário poderia encontrar a documentação para esse tipo).

Alguém foi capaz de implementar algo semelhante ao que estou tentando fazer para os parâmetros ou tipos de retorno, preferencialmente ambos? Ou alguma ideia para me apontar na direção certa?