Как добавить новые столбцы в XML-документацию по Web Api (страница справки)?

Question

Я работаю с последней XML-документацией Web Api, предоставленной nuget в Visual Studio 2012. На самом деле я делаю свои комментарии XML и могу получить справочную страницу класса с такими свойствами:

Name  
Description  
Type  
Additional information  

Мне интересно, могу ли я добавить еще один, чтобы вставить пример данных, но я не могу найти модель в моих комментариях.

Я делаю следующее:

    /// <summary>
    /// My description
    /// </summary>
    /// <example>My example</example>

но это просто не появляется.

Я понимаю, что мне нужно изменить модель, загруженную в Parameters.cshtml для того, чтобы показать его в HTML (это не проблема), но...

Как я могу изменить эту модель?

заранее спасибо

Answer 1

Web API не поддерживает это, поэтому вам придется создавать его самостоятельно. Хотя это не так уж и сложно, вы должны сначала подумать, не добавит ли пример к самому описанию работу достаточно хорошо.

Вид, куда вы должны добавить 3-й столбец:

Areas/HelpPage/Views/Help/DisplayTemplates/ApiGroup.cshtml

Соответствующий фрагмент:

@foreach (var api in Model)
{
    <tr>
        <td class="api-name"><a href="@Url.Action("Api", "Help", new { apiId = api.GetFriendlyId() })">@api.HttpMethod.Method @api.RelativePath</a></td>
        <td class="api-documentation">
        @if (api.Documentation != null)
        {
            <p>@api.Documentation</p>
        }
        else
        {
            <p>No documentation available.</p>
        }
        </td>
    </tr>
}

Затем вы быстро понимаете, что вам нужно взглянуть на ApiDescription модель.

Наиболее актуальные свойства ApiDescription похоже:
- ParameterDescriptions (сборник параметров. выставляет: Name, Source, Documentation)
- ResponseDescription

Это основы. Для реализации правильной справочной страницы этот URL также будет очень полезен: http://blogs.msdn.com/b/yaohuang1/archive/2012/12/10/asp-net-web-api-help-page-part-3-advanced-help-page-customizations.aspx

Ниже моя самая основная реализация, которая перечисляет параметр name а также source

<h2 id="@Model.Key.ControllerName">@Model.Key.ControllerName</h2>
@if (!String.IsNullOrEmpty(controllerDocumentation))
{
    <p>@controllerDocumentation</p>
}
<table class="help-page-table">
    <thead>
        <tr>
            <th>API</th>
            <th>Description</th>
            <th>Params</th>
        </tr>
    </thead>
    <tbody>
        @foreach (var api in Model)
        {
            <tr>
                <td class="api-name"><a href="@Url.Action("Api", "Help", new { apiId = api.GetFriendlyId() })">@api.HttpMethod.Method @api.RelativePath</a></td>
                <td class="api-documentation">
                    @if (api.Documentation != null)
                    {
                        <p>@api.Documentation</p>
                    }
                    else
                    {
                        <p>No documentation available.</p>
                    }
                </td>
                <td class="api-documentation">
                    @foreach (var p in api.ParameterDescriptions)
                    {
                        @p.Name @:- @p.Source
                    }
                </td>
            </tr>
        }
    </tbody>
</table>