Страница справки 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-комментариями) отдельно от вызовов службы, а вызовы службы просто показывают имя возвращаемого ими типа (тогда, по крайней мере, пользователь сможет найти документация для этого типа).
Кто-нибудь смог реализовать что-то похожее на то, что я пытаюсь сделать для параметров или типов возвращаемых данных, предпочтительно для обоих? Или какие-либо идеи, чтобы указать мне в правильном направлении?