如何在 swagger.json 中为 POST 请求传递 formData？答案

【问题标题】：How to pass formData for POST request in swagger.json?如何在 swagger.json 中为 POST 请求传递 formData？
【发布时间】：2019-12-18 17:52:55
【问题描述】：

在我的播放框架应用程序中，我在路由文件中注册了 API：

POST /api/rmt-create-request controllers.Api.CreateRMTRequestForm

在控制器的操作中，我使用以下代码访问通过表单提交提交的 formData：

public Result CreateRMTRequestForm()
    {
        Map<String, String[]> params = request().body().asMultipartFormData().asFormUrlEncoded();

当我使用 forntend 应用程序提交表单时，它作为 API 工作正常。

我正在尝试使用 swagger.ui 创建 API 文档，其中我在 swagger.json 文件中编写了以下 JSON 数据。

"paths": {"/api/rmt-create-request": {
      "post": {
        "tags": [
          "RMT APIs"
        ],
        "description" : "Return newly created request data",
        "operationId": "create-new-rmt-request",
        "consumes": ["application/x-www-form-urlencoded"],
        "parameters": [
          {
            "name": "rootNodeName",
            "in": "formData",
            "description": "Root node class name for item",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/rmt-request-data"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/default"
          }
        }
      }
    },

在检查 RequestHeader 数据时，它没有显示值为 'multipart/form-data' 的 content-Type 属性以及 formData 未附加，这使得控制器抛出 null 异常。

谁能帮助 swagger.json 文件中缺少的内容？

【问题讨论】：

你的swagger.json文件是swagger: '2.0'还是openapi: 3.0.0？
它的“openapi”：“3.0.0”
swagger.json文件是手动写的还是源码生成的？
我是手动写的

标签： java playframework swagger

【解决方案1】：

您正在混合使用 OpenAPI 2.0 和 3.0 语法。

在 OpenAPI 3.0 中，请求正文（包括表单数据）是使用 requestBody 关键字而不是 in: formData 参数定义的。

另外，OAS3 不使用consumes。操作使用的媒体类型在requestBody 中指定。

"paths": {
  "/api/rmt-create-request": {
    "post": {
      "tags": [
        "RMT APIs"
      ],
      "description": "Return newly created request data",
      "operationId": "create-new-rmt-request",
      "requestBody": {
        "content": {
          "multipart/form-data": {    // or  "application/x-www-form-urlencoded" - depending on what you need
            "schema": {
              "type": "object",
              "properties": {
                "rootNodeName": {
                  "type": "string",
                  "description": "Root node class name for item"
                }
              }
            }
          }
        }
      }
    }
  }
}

更多信息：Describing Request Body

【讨论】：