Korzystam ze strony pomocy API Web API z Web API 2 (5.0) - obu najnowszych pakietów Nuget. Chciałbym, aby dokumentacja pomocy pokazywała komentarze właściwości na klasach, które są parametrami lub zwracane w treści HttpResponseMessage.

Na przykład mam metodę kontrolera taką jak ta:

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

Chciałbym komentarze XML, które mam naMyClassType1 iMyClassType2 do wyświetlenia na stronie pomocy dla powyższej akcji post.

Wszędzie, gdzie spojrzałem, do tej pory wydaje się, że nie jest to jeszcze obsługiwane. Zastanawiam się jednak, czy ktoś był w stanie uruchomić to, rozszerzając ApiExplorer, dodając do XmlDocumentationProvider itp.?

Wiem, że komentarze i właściwości są zawarte w wygenerowanym pliku XML, więc mógłbym spróbować przeanalizować go ręcznie (wszystkie typy parametrów i zwrotów są wMyAssemblyName.Models przestrzeń nazw, więc pomyślałem, że mogę szukać węzłów XML, które mają nazwę elementu, zaczynając od tej przestrzeni nazw. Wiem jednak, że wbudowane strony pomocy API WWW mają pewne funkcje buforowania, więc wolę w jakiś sposób włączyć to do istniejącej funkcjonalności (wystarczy dodać do niej).

Udało mi się pokazać typy parametrów (tylko jedna warstwa w dół), aktualizując szablon Parameters.cshtml do tego:

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

gdzieGetFriendlyTypeName() Powyższa metoda została zaimplementowana jak pokazano poniżej:Jak uzyskać poprawną definicję tekstu typu ogólnego za pomocą odbicia?

Nie daje mi to jednak komentarzy z tych klas i nie pomaga w przypadku zagnieżdżonych typów (np. Jeśli mój model miałby złożoną właściwość, nie pokazywałby właściwości tej złożonej właściwości). A typy nie są wystarczająco przydatne bez komentarzy XML.

Dotyczy to również tylko parametrów, ale nie zwraca typów zawartych w treści HttpResponseMessage. Udało mi się uzyskać próbki odpowiedzi, wdrażającResponseTypeAttribute jak pokazano tutaj:Automatyczne generowanie stron pomocy z typem powrotu HttpResponseMessage ale znowu to nie daje mi właściwości z komentarzami XML. Mógłbym użyć refleksji, aby uzyskać typy podobne do tego, jak ponownie otrzymałem typy parametrów, ale naprawdę chciałbym komentarze XML wraz z typami, w tym zagnieżdżone typy złożone.

Byłbym również dopuszczalny, aby dokumentować dokumentację modelu / klasy (właściwości z typami i komentarzami XML) oddzielnie od wywołań usługi, a wywołania usługi po prostu pokazywać nazwę typu, który zwracają (wtedy przynajmniej użytkownik może znaleźć dokumentacja tego typu).

Czy ktoś był w stanie zaimplementować coś podobnego do tego, co próbuję zrobić dla parametrów lub typów zwracanych, najlepiej obu? Lub jakieś pomysły, które wskażą mi właściwy kierunek?