如何用OpenAPI 3.0描述deepObject编码的POST表单请求？

首先，你的问题核心在于**application/x-www-form-urlencoded结合deepObject编码的嵌套Schema引用方式，widdershins工具暂时无法正确解析**，导致生成的文档请求体参数为空。另外注意你的curl示例用的是multipart/form-data，但OpenAPI里写的是application/x-www-form-urlencoded，这也可能是混淆点之一。

下面给你两种可行的解决方案：

方案1：直接平铺表单字段（最简单，兼容大多数工具） #

如果不需要严格复用整个LoginForm对象，或者可以接受在路径里直接定义字段，这种方式最稳妥，widdershins能完美解析：

paths:
  /site/login:
    description: "Authorization"
    post:
      requestBody:
        content:
          # 如果你实际请求是multipart/form-data，就用这个类型
          multipart/form-data:
            schema:
              type: object
              properties:
                LoginForm[login]:
                  type: string
                  description: 用户名
                LoginForm[password]:
                  type: string
                  description: 密码
              required:
                - LoginForm[login]
                - LoginForm[password]
          # 如果是x-www-form-urlencoded，保留这个类型
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                LoginForm[login]:
                  type: string
                LoginForm[password]:
                  type: string
              required:
                - LoginForm[login]
                - LoginForm[password]
components:
  schemas:
    LoginForm:
      type: object
      properties:
        login:
          type: string
        password:
          type: string
      required:
        - login
        - password

方案2：调整引用方式，适配工具解析逻辑 #

如果坚持要复用LoginForm Schema，需要调整编码和Schema的定义方式，确保工具能识别deepObject风格的参数：

paths:
  /site/login:
    description: "Authorization"
    post:
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                LoginForm:
                  $ref: '#/components/schemas/LoginForm'
            encoding:
              LoginForm:
                style: deepObject
                explode: true
          # 如果实际是multipart/form-data，这样定义：
          multipart/form-data:
            schema:
              type: object
              properties:
                LoginForm[login]:
                  $ref: '#/components/schemas/LoginForm/properties/login'
                LoginForm[password]:
                  $ref: '#/components/schemas/LoginForm/properties/password'
              required:
                - LoginForm[login]
                - LoginForm[password]
components:
  schemas:
    LoginForm:
      type: object
      properties:
        login:
          type: string
        password:
          type: string
      required:
        - login
        - password

另外，建议先通过Swagger UI预览调整后的YAML文件，确认请求体参数能正确显示，再用widdershins生成文档，这样能提前验证结构是否正确。

内容的提问来源于stack exchange，提问作者atom-22