Web Api - Auto generating request samples using ApiExplorer

Question

Is there a way to make ApiExplorer auto generate request samples?

I tried using:

config.SetActualResponseType(typeof(SomeType), "ControllerName", "Post"); 

in HelpPageConfig.cs, but 2 problems came up:

1. it requires me to define specific types for specific controllers and actions and I'm looking for something more generic which will not require adding\changing code if a new controller\type was added.

2. I can only use one type per controller\action, so I can't generate a full request sample for an action that receives 2 composite types in it's request body.

Any ideas on how to solve\approach these issues?

Answer 1

As Kiran Challa mentioned in a comment on the OP, the auto generation of samples is part of the Help Pages package, and not the ApiExplorer interface.

For question #1 you're looking to define examples for composite objects wherever they are used. You do this via the SetSampleObjects method in your Help Pages configuration. For example, this is from my HelpPageConfig.Register method:

config.SetSampleObjects(new Dictionary<Type, object>
{
    {typeof(CompositeType1), ModelExamples.GenerateExample<CompositeType1>()},
    {typeof(CompositeType2), ModelExamples.GenerateExample<CompositeType2>()},
    {typeof(CompositeType3), ModelExamples.GenerateExample<CompositeType3>()},
});

where ModelExamples.GenerateExample is a static method/class I use to create example objects of the specified type, keeping this section clean and concise. The above will cause your Help Pages documentation to use your generated examples for return types of CompositeType1, CompositeType2, and CompositeType3.

This brings us to question #2. I assume you're talking about return types consisting of multiple composite types such as:

List<CompositeType1>

or

Tuple<CompositeType1,CompositeType2>

It's not sufficient to have the generated models as above since the Help Pages logic only checks the type of the return as a whole before deciding whether to use your model or generate a generic example. So you need to add entries like this:

config.SetSampleObjects(new Dictionary<Type, object>
{
    {
        typeof(List<CompositeType1>),
        ModelExamples.GenerateExample<List<CompositeType1>>()
    },
    {
        typeof(Tuple<CompositeType1,CompositeType2>),
        ModelExamples.GenerateExample<Tuple<CompositeType1,CompositeType2>>()
    },
});

Now, if you are are using HttpResponseMessage for any of your return types, that's when you use config.SetActualResponseType() like this:

config.SetActualResponseType(
    typeof(List<CompositeType1>), 
    "Foo",
    "ApiMethodA");
config.SetActualResponseType(
    typeof(Tuple<CompositeType1,CompositeType2>), 
    "Bar",
    "ApiMethodB");

TL;DR / Conclusion: The combination of config.SetSampleObjects and config.SetActualResponseType will let you customize what example objects look like in the Help Pages auto-generated documentation in general, and allow you to specify which example objects the response for each method should use.

2016 Edit Responding to a comment. The ModelExamples is just creating sample objects of the specified type. This can be done many ways, but here is one way:

public static class ModelExamples
{
    public static T GenerateExample<T>()
    {
        var retval = default(T);

        if (typeof(T) == typeof(ActionResult))
        {
            var value = ActionResult.Success;
            retval = (T)(object)value;
        }

        // ... whatever other types you handle go here ...

        return retval;
    }
}