1

I'm working with the latest Web Api XML Documentation provided by nuget in Visual Studio 2012. Actually I'm doing my XML comments and I can get a help page of a class with this kind of properties:

Name  
Description  
Type  
Additional information  

I'm wonder if can I add one more to insert an example of the data, but I can't find the model in my comments.

I do the following:

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

but it just doesn't appear.

I understand that I need to change the model loaded in Parameters.cshtml in order to show it in the html (that is not a problem) but...

How can I change this model?

Thanks in advance

2
  • 1
    Actually I could solve it, I'll answer it when I have a little of time. Anyway if you want to response this question, I'll vote up and / or accept it. Commented Dec 3, 2014 at 21:57
  • could you please show us how you selved this? Commented Jun 13, 2016 at 17:08

1 Answer 1

1

Web API has no support for doing this so you will have to build it up yourself. While it's not that difficult, you should consider first if adding the example to the description itself won't get the job done good enough.

The View, where you should add the 3rd column:

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

Relevant snippet:

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

Quickly you then realize you need look at the ApiDescription model.

The most relevant properties of ApiDescription seem to be:
- ParameterDescriptions (collection of parameters. Exposes: Name, Source, Documentation)
- ResponseDescription

These are the basics. In order to implement a proper help page this url will also prove a lot of use: http://blogs.msdn.com/b/yaohuang1/archive/2012/12/10/asp-net-web-api-help-page-part-3-advanced-help-page-customizations.aspx

Below is my very basic implementation which lists parameter name and 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>
Sign up to request clarification or add additional context in comments.

1 Comment

Thanks. Actually I solved it, but I don't have time to answer myself. (As appears in my first comment) And I have to make some more several modifications but this is currently a good helping answer.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.