在Swagger中更改为Url-Form-Encoded Post请求

Question

我想知道是否可以在Swagger中创建一个url-form编码的帖子请求？例如:

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>

目前我们有各种参数的布局,但不知道如何更改为url-form-encoded.我们尝试过更换为in:body标题而不是标题,但这不起作用.请参阅grant-type参数的示例

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

目前返回的是:

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>

对此有任何帮助/见解将不胜感激 - 甚至让我知道它是否可能？

Answer 1

有可能,您只需要将参数的in值设置formData为Parameter对象描述中的OpenAPI(fka.Swagger)规范中所述:

当application/x-www-form-urlencoded或multipart/form-data用作请求的内容类型时(在OpenAPI的定义中,操作的消耗属性),用于描述HTTP请求的有效负载

您还可以阅读我的OpenAPI规范教程的第5部分第1.7节

这是一个例子:

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

Answer 2

对于 OpenAPI 3.0.X - 下面的例子应该会有所帮助

openapi: 3.0.3
info:
  title: Sample Service
  description: Lorem ipsum dolor sit amet, recusabo gloriatur ius ne. 
  version: 1.0.0
tags:
  - name: tag1
    description: tag1 desc
paths:
  /test:
    post:
      tags:
        - tag1
      summary: generates token
      description: ''
      operationId: token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                attr1:
                  type: string
                attr2:
                  type: string
                language:
                  type: string
                  default: en
                  enum:
                    - en
                    - es
              required:
                - language
      responses:
        '200':
          description: Sample response
        '400':
          description: Invalid response

externalDocs:
  url: 'https://github.com/'
  description: 'Additional info'

渲染时，招摇看起来像