Web Api-使用ApiExplorer自动生成请求样本 [英] Web Api - Auto generating request samples using ApiExplorer

问题描述

有没有一种方法可以使ApiExplorer自动生成请求样本?

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

我尝试使用:

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

在HelpPageConfig.cs中，但是出现了两个问题:

in HelpPageConfig.cs, but 2 problems came up:

1. 这需要我为特定控制器和动作定义特定类型，并且我正在寻找更通用的东西，如果不需要，则不需要添加/更改代码添加了新的控制器\类型.

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?

推荐答案

在评论中提到 Kiran Challa 在OP上，示例的自动生成是帮助页面"软件包的一部分，而不是ApiExplorer界面的一部分.

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.

对于问题#1，您正在寻找为复合对象(无论它们在何处使用)定义示例.您可以通过帮助页面"配置中的SetSampleObjects方法执行此操作.例如，这来自我的HelpPageConfig.Register方法:

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>()},
});

其中ModelExamples.GenerateExample是静态方法/类，我使用它创建指定类型的示例对象，从而使本节保持简洁明了.以上将使您的帮助页面文档将生成的示例用于CompositeType1，CompositeType2和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.

这使我们想到了问题2.我假设您正在谈论的是由多个复合类型组成的返回类型，例如:

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

List<CompositeType1>

或

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>>()
    },
});

现在，如果您对任何返回类型都使用HttpResponseMessage，那就是在使用config.SetActualResponseType()时，如下所示:

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/结论: config.SetSampleObjects和config.SetActualResponseType的组合将使您可以自定义帮助页面"自动生成的文档中的示例对象，并且使您能够指定每种方法的响应应使用的示例对象.

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编辑.回复评论. ModelExamples只是创建指定类型的样本对象.这可以通过多种方式完成，但这是一种方式:

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

这篇关于Web Api-使用ApiExplorer自动生成请求样本的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！