Страница справки 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<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() Метод выше реализован так, как показано здесь: Как я могу получить правильное текстовое определение универсального типа, используя отражение?
Однако это не дает мне комментариев от этих классов и не помогает с вложенными типами (например, если бы в моей модели было свойство комплексного типа, свойства этого комплексного типа не отображались бы). И типы все равно недостаточно полезны без их комментариев XML.
Кроме того, это относится только к параметрам, но не к возвращаемым типам, содержащимся в теле HttpResponseMessage. Я смог получить образцы ответов для работы путем реализации ResponseTypeAttribute как показано здесь: автоматически сгенерированные страницы справки с возвращаемым типом HttpResponseMessage, но опять же, которые не дают мне свойств с комментариями XML. Я мог бы использовать отражение, чтобы получить типы аналогично тому, как я снова получал типы параметров, но я действительно хотел бы, чтобы комментарии XML вместе с типами включали вложенные сложные типы.
Я также считаю приемлемым документировать документацию модели / класса (свойства с типами и XML-комментариями) отдельно от вызовов службы, а вызовы службы просто показывают имя возвращаемого ими типа (тогда, по крайней мере, пользователь сможет найти документация для этого типа).
Кто-нибудь смог реализовать что-то похожее на то, что я пытаюсь сделать для параметров или типов возвращаемых данных, предпочтительно для обоих? Или какие-либо идеи, чтобы указать мне в правильном направлении?
2 ответа
Функция документирования отдельных свойств сложного типа в настоящее время находится в разработке и будет доступна для следующего выпуска. Тем не менее, вы можете получить пакет HelpPage из сборок Nightly и попробовать его. Вы должны иметь возможность обновить этот пакет до существующего проекта веб-API 5.0.
Также в настоящее время мы документируем только типы ввода действия, а не типы ответов, так как обычно пользователи хотят знать об информации типов ввода. Но я вижу, что пользователям может потребоваться информация о типе ответа и для потребления... мы рассмотрим это и сообщим вам.
Вы можете внести изменения, чтобы включить html в комментарии к документации.
После того, как вы разрешите HTML, вы можете поместить таблицу с информацией о свойствах, куда идет описание тега param для документации XML. Вы также можете просмотреть исходный HTML-код страницы справки, чтобы получить имена атрибутов класса, которые используются для таблиц страниц справки, чтобы ваша таблица использовала тот же CSS, что и все другие таблицы.
Это взлом, но он работает отлично.