Web Api — автоматическое создание образцов запросов с помощью ApiExplorer

Как упоминал Kiran Challa в комментарии к OP, автоматическое создание образцов является частью пакета страниц справки, а не интерфейс ApiExplorer.

Для вопроса № 1 вы хотите определить примеры для составных объектов, где бы они ни использовались. Вы делаете это с помощью метода SetSampleObjects в конфигурации страниц справки. Например, это из моего метода HelpPageConfig.Register:

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

где ModelExamples.GenerateExample — это статический метод/класс, который я использую для создания примеров объектов указанного типа, сохраняя этот раздел чистым и кратким. Вышеприведенное приведет к тому, что ваша документация на страницах справки будет использовать созданные вами примеры для возвращаемых типов CompositeType1, CompositeType2 и CompositeType3.

Это подводит нас к вопросу №2. Я предполагаю, что вы говорите о возвращаемых типах, состоящих из нескольких составных типов, таких как:

List<CompositeType1>

or

Tuple<CompositeType1,CompositeType2>

Недостаточно иметь сгенерированные модели, как указано выше, поскольку логика страниц справки только проверяет тип возврата в целом, прежде чем решить, использовать ли вашу модель или создать общий пример. Итак, вам нужно добавить такие записи:

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

Теперь, если вы используете HttpResponseMessage для любого из ваших возвращаемых типов, это когда вы используете config.SetActualResponseType() следующим образом:

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

TL;DR / Заключение: комбинация config.SetSampleObjects и config.SetActualResponseType позволит вам настроить внешний вид примеров объектов в автоматически созданной документации справочных страниц в целом, а также позволит вам указать, какой пример объекты, которые должен использовать ответ для каждого метода.

2016 Edit Ответ на комментарий. ModelExamples просто создает образцы объектов указанного типа. Это можно сделать многими способами, но вот один из них:

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