Samples in ASP.NET Web API Help Page are automatically generated based on your action parameters and return types. They represent the kind of contents that could go into the request or response body. For instance, if you have the Delete action inside ValuesController like below:
The help page would give you the following samples:
Understanding how samples are generated
Before we get into customization, it’s worth understanding how these samples are generated. For starters, it uses ApiExplorer to figure out the body parameter type and the return type of you action. Then it will try to create an instance of these types with dummy data. Finally, it ask ApiExplorer for the appropriate formatters to write the created instance into the sample string.
Now that you understand how the samples are generated, there shouldn’t be any surprise when you see something like “Failed to generate the sample for media type 'application/x-www-form-urlencoded'” on the help page:
Yes, that’s because the default JQueryMvcFormUrlEncodedFormatter doesn’t support writing. However, you can still make it work by setting custom samples.
Setting custom samples
Most of the help page customizations can be done in HelpPageConfig.cs. If you open the file, you’ll see a bunch of commented codes that show you different ways of providing custom samples to the help page.
One way of solving the problem described above is by using SetSampleForType, which allow you to set the sample string directly. For instance, setting the following will have the help page display “Id=123&Name=Foo&Date=2012-10-13” as the application/x-www-form-urlencoded sample for actions with CompositeValue.
And there’re other ways of customizing the samples that you can explore on your own:
Setting the samples when the action returns an HttpResponseMessage
When the action returns an HttpResponseMessage, the content of the response body becomes unpredictable based on the signature. Therefore, by default the help page simply doesn’t know what sample to display. However, you easily customize it to show the right sample.
Consider the following two scenarios where you return an HttpResponseMessage:
HttpResponseMessage with content negotiation
This is when your action supports content negotiation. Something like below:
Here you simply need to use SetActualResponseType to indicate the actual type that goes into the body of the HttpResponseMessage. You can set this in the HelpPageConfig.cs:
As a result, the help page would now display the right samples for the Post action above.
HttpResponseMessage without content negotiation
This is when you’re returning the HttpResponseMessage without the content negotiation. Something like the following where the content is simply a StringContent.
Here you can simply control what sample to display for the action by using SetSampleResponse:
This will have the help page display the following sample for the Custom action above.