使用 Swagger 2.0 描述复杂对象数组 [英] Describe an array of complex objects using Swagger 2.0

问题描述

我有一个 Web Api 2 项目，该项目有一个 HttpGet 方法，该方法将复杂对象列表作为参数.像这样:

I have a Web Api 2 project that has an HttpGet method that takes a list of complex objects as the parameter. Like this:

[HttpGet]
public string GetCoolStuff(List<ContainerContract> containers)

我正在使用 swashbuckle 来设置我的 swagger 文档.但是它像这样设置这个参数:

I am using swashbuckle to setup my swagger docs. But it sets this parameter up like this:

{
  "name" : "containerContracts",
  "in" : "query",
  "required" : true,
  "type" : "array",
  "items" : {},
  "collectionFormat" : "multi"
}

至少 items 对象似乎需要一些东西.

At the very least the items object seems like it needs something in it.

后来在 definitions 部分我确实发现了这个:

Later down in the definitions section I did find this:

"ContainerContract" : {
    "type" : "object",
    "properties" : {
        "Type" : {
            "type" : "string"
        },
        "Temperature" : {
            "type" : "string"
        },
        "CreatedWhen" : {
            "format" : "date-time",
            "type" : "string"
        }
    }

不过好像没有用过...

But it does not seem to be used...

有没有一种方法可以让我大摇大摆地理解这是一个对象列表，并给我一种方法来输入各个属性的值?(就像我对复杂对象所做的那样不是列表.)

Is there a way I can set this up to have swagger understand that this is a list of objects and give me a way to enter values for the individual properties? (Like I do for complex objects that are not lists.)

这是我在图片中的意思:

Here is what I mean in a picture:

还是 Swagger Ui 还没有那么聪明?(如果我必须编写 Json 来填写我的列表，那么我可以.)

Or is Swagger Ui just not that smart yet? (If I have to write Json to fill in my lists then I can.)

以防万一，这是一个ContainerContract的例子:

Just incase it matters, here is an example of ContainerContract:

public class ContainerContract
{
    public string Type { get; set; }
    public char Temperature { get; set; }
    public DateTime CreatedWhen { get; set; }
}

推荐答案

不幸的是，在 2.0 规范(Swashbuckle 使用的规范)中，您不能在查询参数中使用复杂对象，即使在数组中也是如此.因此，直到下一个版本才支持您要执行的操作.您可以拥有一个数组，但 items 必须是原始值类型.

unfortunately in the 2.0 specification (which Swashbuckle uses), you cannot have complex objects in query parameters, even in arrays. So what you're looking to do is not supported until the next version. You can have an array, but the items must be a primitive value type.

这篇关于使用 Swagger 2.0 描述复杂对象数组的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！