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

Question

我想发布一个字符串数组

[
  "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.

Answer 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/

Answer 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及更高版本中得到修复,理想情况下您应该升级到该版本.

Answer 3

没有一个答案对我有用。正如以下 Baeldung 文章所述：

为了更好地记录 API 并指导用户，我们可以使用如何插入值的示例标签

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

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 编辑器中更好地通知示例值。