Страница справки 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());
}

Я хотел бы, чтобы комментарии XML, которые я имею наMyClassType1 а такжеMyClassType2 отображаться на странице справки для указанного выше действия.

Куда бы я ни посмотрел, кажется, что это пока не поддерживается. Тем не менее, мне интересно, если кто-нибудь смог заставить это работать, расширив ApiExplorer, добавив XmlDocumentationProvider и т. Д.?

Я знаю, что комментарии и свойства включены в генерируемый XML-файл, поэтому я мог бы попытаться разобрать его вручную (все параметры и возвращаемые типы находятся вMyAssemblyName.Models пространство имен, поэтому я подумал, что я мог бы искать узлы XML, имена членов которых начинаются с этого пространства имен. Однако я знаю, что встроенные страницы справки веб-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()
                            <br>
                        }
                    
                    <pre>@parameterDocumentation</pre>
                    
                        @switch(parameter.Source)
                        {
                            case ApiParameterSource.FromBody:
                                <p>Define this parameter in the request body.</p>
                                break;
                            case ApiParameterSource.FromUri:
                                <p>Define this parameter in the request URI.</p>
                                if (parameter.ParameterDescriptor.IsOptional)
                                {
                                    <p>This parameter is optional.</p>
                                }
                                break;
                            default:
                                <p>None.</p>
                                break;
                        }
                    
                
            }
        }
    

гдеGetFriendlyTypeName() Метод выше реализован так, как показано здесь:Как я могу получить правильное текстовое определение универсального типа, используя отражение?

Тем не менее, это нене получите мне комментарии от этих классов, и это неt помочь с вложенными типами (например, если бы в моей модели было свойство комплексного типа, свойства этого комплексного типа не были бы показаны). И типы все равно недостаточно полезны без их комментариев XML.

Кроме того, это относится только к параметрам, но не к возвращаемым типам, содержащимся в теле HttpResponseMessage. Я смог получить образцы ответов для работы путем реализацииResponseTypeAttribute как показано здесь:Автоматически сгенерированные справочные страницы с типом возврата HttpResponseMessage но опять же это неНе дайте мне свойства с комментариями XML. Я мог бы использовать отражение, чтобы получить типы аналогично тому, как я снова получал типы параметров, но я действительно хотел бы, чтобы комментарии XML вместе с типами включали вложенные сложные типы.

Я также считаю приемлемым документировать документацию модели / класса (свойства с типами и XML-комментариями) отдельно от вызовов службы, а вызовы службы просто показывают имя возвращаемого ими типа (тогда, по крайней мере, пользователь сможет найти документация для этого типа).

Кто-нибудь смог реализовать что-то похожее на то, что я пытаюсь сделать для параметров или типов возвращаемых данных, предпочтительно для обоих? Или какие-либо идеи, чтобы указать мне в правильном направлении?

Ответы на вопрос(2)

Ваш ответ на вопрос