api - 使用 ServiceStack 的 Swagger 插件，如何实现带有预设值列表的字符串字段

Question

我正在使用 ServiceStack 的新 Swagger 插件实现 Swagger API 文档，并试图确定如何使用“容器”数据类型。我需要显示一个字符串字段，其中包含一个预先确定的值列表和其他子对象列表的参数。

除非我遗漏了一些东西，否则我相信 swagger 只能采用一个文本字段，您可以为子对象列表输入 JSON。我相信这段代码应该可以解决问题。

[ApiMember(Name = "Connections", Description = "insert JSON sample here", ParameterType = "body", DataType = "container", IsRequired = false, Verb = "Post")]

我不知道(我希望有人可以帮助我)是否可以有一个来自预设值列表的字符串字段。在 Swagger 中，此代码片段说明了如何执行此操作。

"Pet":{
    "id":"Pet",
    "properties":{
    ...
      "status":{
        "type":"String",
        "description":"pet status in the store",
        "allowableValues":{
          "valueType":"LIST",
          "values":[
            "available",
            "pending",
            "sold"
          ]
        }
      },
      "happiness": {
        "type": "Int",
        "description": "how happy the Pet appears to be, where 10 is 'extremely happy'",
        "allowableValues": {
          "valueType": "RANGE",
          "min": 1,
          "max": 10
        }
      },
      ...

有谁知道这是如何使用 ServiceStack.Api.Swagger 完成的？

Answer 1

我一直在为同样的问题苦苦挣扎，但意识到目前不支持此功能。您基本上不能使用模型 POST 或 PUT 数据。这个功能还在不断变化中，正在开发中，所以我想它在待办事项列表中。

如果查看源代码，会看到没有Models ResourcesResponse 中支持的属性数据合约:

[DataContract]
public class ResourcesResponse
{
    [DataMember(Name = "swaggerVersion")]
    public string SwaggerVersion { get; set; }
    [DataMember(Name = "apiVersion")]
    public string ApiVersion { get; set; }
    [DataMember(Name = "basePath")]
    public string BasePath { get; set; }
    [DataMember(Name = "apis")]
    public List<RestService> Apis { get; set; }
}

如果将其与 Wordnik 上的 Petstore 示例进行比较，您会发现模型作为根节点包含在内:

{
   "apiVersion":"0.2",
   "swaggerVersion":"1.1",
   "basePath":"http://petstore.swagger.wordnik.com/api",
   "resourcePath":"/pet",
   "apis":[
      {
         "path":"/pet.{format}",
         "description":"Operations about pets",
         "operations":[
            {
               "httpMethod":"POST",
               "summary":"Add a new pet to the store",
               "responseClass":"void",
               "nickname":"addPet",
               "parameters":[
                  {
                     "description":"Pet object that needs to be added to the store",
                     "paramType":"body",
                     "required":true,
                     "allowMultiple":false,
                     "dataType":"Pet"
                  }
               ],
               "errorResponses":[
                  {
                     "code":405,
                     "reason":"Invalid input"
                  }
               ]
            }
         ]
      }
   ],
   "models":{
      "Category":{
         "id":"Category",
         "properties":{
            "id":{
               "type":"long"
            },
            "name":{
               "type":"string"
            }
         }
      },
      "Pet":{
         "id":"Pet",
         "properties":{
            "tags":{
               "items":{
                  "$ref":"Tag"
               },
               "type":"Array"
            },
            "id":{
               "type":"long"
            },
            "category":{
               "type":"Category"
            },
            "status":{
               "allowableValues":{
                  "valueType":"LIST",
                  "values":[
                     "available",
                     "pending",
                     "sold"
                  ],
                  "valueType":"LIST"
               },
               "description":"pet status in the store",
               "type":"string"
            },
            "name":{
               "type":"string"
            },
            "photoUrls":{
               "items":{
                  "type":"string"
               },
               "type":"Array"
            }
         }
      },
      "Tag":{
         "id":"Tag",
         "properties":{
            "id":{
               "type":"long"
            },
            "name":{
               "type":"string"
            }
         }
      }
   }
}

我认为解决这个问题的唯一方法是自己发布整个对象。有一个接受整个对象的请求对象，例如 Pet。设置 ParameterType至 body和 DataType至 Pet .在 Swagger 界面中，您将看到一个文本区域，您必须在其中粘贴实际的 JSON 对象。您的请求将如下所示:

[Api("The Thing Service")]
[Route("/thing", "POST", Summary = @"POST a new thing", Notes = "Send a thing here")]
public class ThingRequest
{
    [DataMember]
    [ApiMember(Name = "Thing", Description = "The thing", ParameterType = "body", DataType = "Thing", IsRequired = false)]
    public ThingDto Thing { get; set; }
}

你的服务是这样的:

/// <summary>
/// Summary description for ThingService
/// </summary>
public class ThingService : Service
{
    public IThingRepository ThingRepository { get; set; }

    public object Post(ThingRequest request)
    {
        var thing = Thing.Map(request);
        ThingRepository.Save(thing);
        return new ThingResponse();
    }
}

将呈现以下内容:



像这样输入对象，请求就会被正确解析: