ASP.Net Web API Help Pages: Ignore certain properties

Question

Is it possible to have the Help Page sample generator ignore certain properties of a particular type?

For example, we use the same DTO for object Request and Response messages, for both POST and PUT requests. When user is POSTing a model (creating a new record) they don't need to provide the ID field.

But once its created and we serialize the new record into the response body, the ID field is included and returned to the client.

So in the POST request sample, I don't want the ID field to be displayed because for post request it doesn't make sense.

But the POST response sample, I do want the ID field displayed...

I am aware that there is the ApiExplorerSettings attribute which can be applied to a Class or Method...but is there anything similar for a Property?

Something like this would be great:

public class MyDTO
{
    [ApiExplorerSettings(IgnoreForRequestApi = true, IgnoreForResponseApi = false)]
    public int Id { get; set; }

    // Other properties omitted for brevity...
}

Answer 1

Using the following annotation I've successfully hidden a property from the generation!

[ApiExplorerSettings(IgnoreApi = true)]

Answer 2

No, there isn't a similar option for a property. HelpPage uses formatter instances configured on the application to serialize the samples and as you can imagine the formatters must not have this knowledge within themselves.

Regarding workarounds:

a. You could explicitly set the raw sample for a particular action's requestsample via the SetSampleRequest extension of HttpRequestMessage. You should be able to see some examples about this in the file at *Areas\HelpPage\App_Start\HelpPageConfig.cs*.

b. In the file Areas\HelpPage\SampleGeneration\HelpPageSampleGenerator.cs, there is a method called WriteSampleObjectUsingFormatter which uses the application's formatter instances to write the samples. Here you would need to create new formatter instances having similar settings as your normal application has(so that they reflect the exact serialization/deserialization semantics that your application would normally react to when actual requests are made) and then try to hide the properties which you want to. We want to create new instances because we do not want to disturb the normal functioning of the application.

Example: In case of Json, you could create a new Json formatter instance and provide a ContractResolver which can hide the properties. Check this link: http://james.newtonking.com/projects/json/help/html/ConditionalProperties.htm

In case of Xml, I am not sure how we can hide properties without using the IgnoreDataMember attribute and also being non-intrusive.

Currently I would prefer option 'a' as its comparatively a simple workaround than 'b'.

Answer 3

ASP.NET WEB API uses Json.NET for JSON and DataContarctSerailizer for XML formatting so if you add [JsonIgnore] annotations over properties that you do not want included in your serialization should work just fine.