嵌入式Swagger无法正确生成x-www-form-urlencoded请求体的原因

核心是OpenAPI Generator的Spring代码生成模板存在参数注解映射错误，具体链路如下：

• 对于application/x-www-form-urlencoded类型的POST表单请求，生成器错误地将表单字段参数标记为了@RequestParam。按照Spring和Swagger的默认逻辑，@RequestParam注解代表参数从URL查询字符串中获取，不属于请求体内容。
• springfox-swagger2扫描到@RequestParam注解后，会默认将这两个参数识别为URL查询参数，因此生成的curl请求把username、password直接拼接到了URL后，请求体为空，也没有携带Content-Type: application/x-www-form-urlencoded请求头。
• 而接口上的@RequestMapping明确声明了consumes = {"application/x-www-form-urlencoded"}，Spring收到请求后会先校验Content-Type是否匹配，由于Swagger/生成客户端发出的请求没有携带对应媒体类型头，直接被拦截返回415 Unsupported Media Type错误。
• Postman请求能正常响应，是因为你手动配置了x-www-form-urlencoded格式的请求体、自动携带了正确的Content-Type头，绕开了Swagger/生成客户端的参数位置错误问题。

补充：如果你的接口定义是基于OpenAPI 2.0（Swagger 2）规范，错误根源是生成器将in: formData类型的参数错误映射为@RequestParam；如果是OpenAPI 3.x规范，则是生成器没有正确识别requestBody中application/x-www-form-urlencoded类型的属性，错误将其作为查询参数处理。

临时规避（无需修改Generator） #

调整你的OpenAPI规范文件，不要将表单字段拆分为独立的query参数，而是明确定义表单请求体：

paths:
  /v1.0/login:
    post:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                password:
                  type: string
      # 其余响应、配置保持不变

重新生成代码后，参数注解会被正确映射，Swagger和生成的客户端会自动将参数放到form表单请求体中，携带正确的Content-Type头。

Generator补丁逻辑（用于提交bug修复） #

需要修改Spring服务端生成器的模板与参数类型映射逻辑：

• 对参数位置的判断逻辑增加分支：仅当参数明确属于query位置时，才生成@RequestParam注解；
• 属于OpenAPI 2.0的formData类型、OpenAPI 3.x中application/x-www-form-urlencoded请求体的字段，不要添加@RequestParam注解，统一使用@ModelAttribute注解绑定表单参数，同时在Swagger的@Parameter注解中明确标注参数属于form表单位置，避免Swagger将参数识别为URL查询参数。

内容的提问来源于stack exchange，提问作者user18619318