在swagger API中将字符串数组指定为body参数

时间:2016-09-01 22:01:19

标签: rest swagger swagger-2.0

我想发布像

这样的字符串数组
[
  "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

5 个答案:

答案 0 :(得分:24)

您对字符串数组的描述是正确的,但参数定义错过了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/

答案 1 :(得分:5)

我已经创建了一个昂首阔步的问题,因为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及更高版本中得到修复,理想情况下您应升级到该版本。

答案 2 :(得分:2)

对于包含Object作为其内容的Array,Object的定义也可以使用定义& $ REF 即可。 示例:

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

答案 3 :(得分:1)

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

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

因此,完整的工作示例将是这样的:

innerHTML

您可以在Swagger editor中查看如何更好地告知示例值。

答案 4 :(得分:0)

得票最多的答案使我朝着正确的方向前进。我只需要一个对象数组的示例,其中每个对象都有一个属性,该属性是一个字符串数组,在strings数组中有多个值。 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"]

要记住的一件事是,缩进对于大张旗鼓至关重要。如果您缩进得不好,招摇将给您奇怪的错误消息。