Changing to Url-Form-Encoded Post Request in Swagger

Question

I was wondering is it possible to create a url-form-encoded post request within Swagger? For example:

POST https://url.co.uk
Host: server.example.com
Authorization: Bearer <Initial Access Token>
Content-Type: application/x-www-form-urlencoded

&grant_type=password
&client_id=<client id>
&client_secret=<client secret>

Currently we have the layout below for our various parameters but are not sure how to change to url-form-encoded. We have tried changing toin:bodyinstead of header but this does not work. See example for grant-type parameter

          "parameters": [
                {
                    "in": "header",
                    "name": "grant_type",
                    "description": "Indicates that the app is using the Resource Owner Password \"password\".",
                    "required": true,
                    "type": "string",
                    "enum": [
                        "password"
                        ] 
                },

Which currently returns this:

Accept: application/json
Accept-Encoding: gzip,deflate,sdch
Accept-Language: en-US,en;q=0.8,fa;q=0.6,sv;q=0.4
Cache-Control: no-cache
Connection: keep-alive
Origin: http://editor.swagger.io
Referer: http://editor.swagger.io/
User-Agent: Mozilla/5.0 
grant_type: password
client_id: xxx-xxx-xxx
client_secret: <client_secret>

Any help/insight on this would be greatly appreciated - even to let me know if it is even possible?

Answer 1

It's possible, you just need to set parameter's in value to formData as explained in in the OpenAPI (fka. Swagger) specification in the Parameter object description:

Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded or multipart/form-data are used as the content type of the request (in OpenAPI's definition, the consumes property of an operation)

You can also read part 5 section 1.7 of my OpenAPI specification tutorial

Here's an example:

swagger: '2.0'

info:
  version: 1.0.0
  title: Form data API
  description: Using form data body parameters

paths:

  /examples:
    post:
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: grant_type
          type: string
          in: formData
        - name: client_id
          type: string
          in: formData
        - name: client_secret
          type: string
          in: formData
      responses:
        200:
          description: OK