CODEWITHSUNDEEP
.netasp.net-web-api
chobo2
chobo2

Reputation: 85765

Webapi Help Page - How to create custom Data? Defenintions and specify what is required?

I am looking at the Webapi Help Page to generated docmentation but all the tutorials I see leave me wondering.

Q1. How do I populate the sample data myself? From my understanding it looks at the data type and makes some data based on the datatype. Some of my data has specific requirements(ie length can't be more than 5 characters).

How do I write my own sample data for each method?

Q2 How can I hide warning messages.

I get this message

Failed to generate the sample for media type 'application/x-www-form-urlencoded'. Cannot use formatter 'JQueryMvcFormUrlEncodedFormatter' to write type 'ProductDM'.

I am not really sure what "x-www-form-urlencoded" is but say if I don't support that how can I just hide that message or say "not supported"?

Q3 How can I write a description for each parameter. In most cases it is clear what they are but in some cases maybe not. Also it would be nice if it automatically took the annotations and put that beside them as well to show that maybe parameter A is option while parameter B is not.

Upvotes: 3

Views: 7146

Answers (2)

Tetsuto Yabuki
Tetsuto Yabuki

Reputation: 96

Regarding Q2 "How can I hide warning messages", in Areas/HelpPage/Views/Help/DisplayTemplates/Samples.chtml, you can add an if statement in the code:

@foreach (var mediaType in mediaTypes)
    {
        if (mediaType != "application/x-www-form-urlencoded") { /// <--- line added here
            <h4 class="sample-header">@mediaType</h4>
            <div class="sample-content">
                <span><b>Sample:</b></span>
                @{
                    var sample = samples[mediaType];
                    if (sample == null)
                    {
                        <p>Sample not available.</p>
                    }
                    else
                    {
                        @Html.DisplayFor(s => sample);
                    }
                }
            </div>
        } /// <----- closing parenthesis
    }

In my case I was already displaying the POST data structure so the "x-www-form-urlencoded" section was not needed. The helpPageConfig also displays a query string by default whereas my methods only accepted objects.

Upvotes: 0

Kiran
Kiran

Reputation: 57949

Q1: Have you taken a look at "Areas\HelpPage\App_Start\HelpPageConfig.cs" file. You should see a bunch of commented out with examples how you could define your own samples.

Example:

public static class HelpPageConfig
{
    public static void Register(HttpConfiguration config)
    {
        //// Uncomment the following to use the documentation from XML documentation file.
        //config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

        //// Uncomment the following to use "sample string" as the sample for all actions that have string as the body parameter or return type.
        //// Also, the string arrays will be used for IEnumerable<string>. The sample objects will be serialized into different media type 
        //// formats by the available formatters.
        //config.SetSampleObjects(new Dictionary<Type, object>
        //{
        //    {typeof(string), "sample string"},
        //    {typeof(IEnumerable<string>), new string[]{"sample 1", "sample 2"}}
        //});

Q2: You are seeing the error for "application/x-www-form-urlencoded" mediatype because the formatter which we use for it can only deserialize or read the data and cannot write. Here the error is to indicate that it only cannot write the sample, but if you infact are sending data in this media type, it could be deserialized correctly. Instead of hiding this section, you could provide an explicit sample for this media type. The HelpPageConfig.cs has examples for this:

//// Uncomment the following to use "[0]=foo&[1]=bar" directly as the sample for all actions that support form URL encoded format
//// and have IEnumerable<string> as the body parameter or return type.
//config.SetSampleForType("[0]=foo&[1]=bar", new MediaTypeHeaderValue("application/x-www-form-urlencoded"), typeof(IEnumerable<string>));

Q3: For documentation about parameters of an action, you can always use the regular comments(summary, param etc) and generate the documentation file and point it like the following:

//// Uncomment the following to use the documentation from XML documentation file.
//config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

We currently do not have support for generating documentation out of Data Annotations, we currently have an issue tracing it: http://aspnetwebstack.codeplex.com/workitem/877

Upvotes: 11

Related Questions