多部分 POST 请求中带有参数的 Swagger 错误

Question

我正在使用 Swagger Editor 来记录现有的 API，内置于 Node，但它一直给我以下错误：

Schema error at paths./upload/Rate.post.parameters[0] is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>

这个错误出现在我的代码的 3 个地方：

路径。/upload/Rate.post.parameters[0]
路径。/upload/Rate.post.parameters[1]
路径。/users/register.post.parameters[0]

我搜索了很多，但是，例如，这个 link 没有解决我的问题，尽管它是同样的错误：

这是我的 Swagger 定义：

  /users/register:
    post:
      tags:
      - "users"
      description: Allows an user to register at the Server
      produces:
        - application/json
      parameters:
        - name: body
          in: body
          description: JSON Object with information for a Register request from an User
          schema: 
            type: object
            required:
              - username
              - password
              - weight
              - height
              - gender
              - restRate
              - age
            properties:
              username:
                type: string
              password:
                type:
                format: password
              weight:
                type: integer
              height:
                type: integer
              gender:
                type: string
              restRate:
                type: integer
              age: 
                type: integer
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Register successful
          schema:
            type: string

  /upload/Rate:
    post:
      tags:
      - "upload"
      description: Allows an user to upload a file into the server
      produces:
        - application/json
      consumes: 
        - multipart/form-data
      parameters:
        - name: body
          in: formData
          description: JSON Object with information for an upload request from an User
          required: false
          schema:
            type: object
            required:   
              - user
              - overlap
              - window 
              - latitude
              - longitude
              - time
              - date
            properties:
              user:
                type: string
              overlap:
                type: string
              window:
                type: string
              latitude:
                type: string
              longitude:
                type: string
              time:
                type: string
              date:
                type: string
        - name: files 
          in: formData
          description: File with the corresponding Rate
          required: false
          schema:
            type: object
            required:
              - rate
            properties:
              rate:
                type: file
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: Login successful
          schema:
            type: string

也许这会有所帮助，但是 post 路由 (upload/Rate) 应该会收到一个类似这样的请求，一旦我解析了它的参数：

user = req.body.user;
rr = req.files.rate;
overlap = req.body.overlap;
windowT = req.body.window;
latitude = req.body.latitude;
longitude = req.body.longitude;
time = req.body.time;
date = req.body.date;

感谢您的帮助和时间！

Answer 1

存在多个问题。

/upload/register:

架构属性 password 缺少 type 的值。
属性名称不匹配 - restHR（在 properties 下）与 restRate（在 required 列表中）。

upload/Rate:

这里的问题是由multipart/form-data请求中的对象参数引起的。在 OpenAPI (fka Swagger) 2.0 中，表单参数可以是原始值和数组，但不能是对象。所以你的例子不能用 OpenAPI 2.0.
来描述
如果您正在设计一个新的 API（或者如果您可以并且愿意更改 API 实现以与 OpenAPI 2.0 兼容），可能的解决方案是:
- 更改操作以使用 application/json 并将所有输入参数合并到一个 JSON 对象中。文件参数需要作为 base64 字符串实现 - type: string 和 format: byte.
- 使用 multipart/form-data 但将对象参数拆分为单独的表单参数。
即将推出的 OpenAPI 3.0 将支持表单数据中的对象参数：
https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#special-considerations-for-multipart-content

多部分 POST 请求中带有参数的 Swagger 错误

Swagger error with parameters in a multipart POST request

swagger

swagger-2.0

swagger-editor