在 swagger API 中指定字符串数组作为 body 参数答案

【问题标题】：Specify an array of strings as body parameter in swagger API在 swagger API 中指定字符串数组作为 body 参数
【发布时间】：2017-01-09 22:17:01
【问题描述】：

我想发布一个字符串数组，例如

[
  "id1",
  "id2"
]

到基于 Swagger 的 API。在我的招摇文件中，我有这些行：

paths:
  /some_url:
    post:
      parameters:
        - name: ids
          in: body
          required: true

将ids的类型指定为字符串数组的正确方法是什么？

更新：

根据规范，以下应该在我的选项中起作用：

  parameters:
    - in: body
      description: xxx
      required: true
      schema:
        type: array
        items:
          type: string

https://github.com/Yelp/swagger_spec_validator 不接受它并返回一长串令人费解的错误，看起来代码需要一些 $ref。

【问题讨论】：

标签： rest swagger swagger-2.0

【解决方案1】：

您对字符串数组的描述是正确的，但参数定义错过了name 属性有效。

这是一个完整的工作示例：

swagger: "2.0"

info:
  title: A dummy title
  version: 1.0.0

paths:
  /path:
    post:
      parameters:
        - in: body
          description: xxx
          required: true
          name: a name
          schema:
            type: array
            items:
              type: string
      responses:
        default:
          description: OK

尝试使用在线编辑器检查您的 OpenAPI（fka.Swagger）规范：http://editor.swagger.io/

【讨论】：

需要注意的是最新的swagger codegen (2-2-3)这个构造会给出一个空指针异常。您将不得不使用对类型的引用。

【解决方案2】：

我创建了一个招摇的问题，因为 Arnaud 提供的帮助虽然是有效的 yaml，但在尝试生成时会给你 NPE 异常。您需要提供如下对象：

  myDataItem:
    type: object
    description: A list of values
    required:
      - values
    properties:
      values:
        type: array
        items:
            type: string

然后参考它（在您的帖子等中）：

  schema:
    $ref: "#/definitions/myDataItem"

供参考github问题：

https://github.com/swagger-api/swagger-codegen/issues/6745

请注意，该问题已在 2.3.0 及更高版本中得到修复，理想情况下您应该升级到该版本。

【讨论】：

【解决方案3】：

没有一个答案对我有用。正如following Baeldung article中所述：

为了更好地记录 API 并指导用户，我们可以使用 example 标签来说明如何插入值

所以完整的工作示例应该是这样的：

swagger: "2.0"

info:
  title: A dummy title
  version: 1.0.0

paths:
  /path:
    post:
      parameters:
        - in: body
          description: xxx
          required: true
          name: a name
          schema:
            type: array
            items:
              type: string
            example: ["str1", "str2", "str3"]
      responses:
        default:
          description: OK

您可以在Swagger editor 中查看现在如何更好地了解示例值。

【讨论】：

【解决方案4】：

对于内容为Object的Array，Object的定义也可以用definitions & $ref表示。示例：

schema:
    type: array
    items:
        $ref: '#/definitions/ObjectSchemaDefinition'
definitions:
    ObjectSchemaDefinition:
        type: string

【讨论】：

【解决方案5】：

得票最多的答案让我朝着正确的方向前进。我只需要一个对象数组的示例，其中每个对象都有一个属性，该属性是字符串数组中具有多个值的字符串数组。 Thanks to the documentation 我是这样工作的：

MyObject:
  type: object
  properties:
    body:
      type: array
      items:
        type: object
        properties:
          type: 
            type: string
          values: 
            type: array
            items:
              type: string
      example: 
        - type: "firstElement"
          values: ["Active", "Inactive"]
        - type: "SecondElement"
          values: ["Active", "Inactive"]

要记住的一件事是，缩进对于 Swagger 至关重要。如果缩进不好，swagger 会给你奇怪的错误信息。

【讨论】：