How to pass formData for POST request in swagger.json?

Question

In my play framework application, I have registered APIs in route file as:

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

On action of controller, I am using following code to access formData submitted with form submit as :

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

Its working fine as API when I submit the form with forntend application.

I am trying to create APIs documentation with swagger.ui in which within swagger.json file I have written following JSON data.

"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"
          }
        }
      }
    },

While inspecting RequestHeader data, its not showing content-Type property with value 'multipart/form-data' as well as formData are not attached, which makes controller to throw null exception.

Can anyone help whats missing in swagger.json file ?

Answer 1

You are mixing OpenAPI 2.0 and 3.0 syntax.

In OpenAPI 3.0, request body (including form data) is defined using the requestBody keyword instead of in: formData parameters.

Also, OAS3 does not use consumes. The media types consumed by the operation are specified inside the 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"
                }
              }
            }
          }
        }
      }
    }
  }
}

More information: Describing Request Body