Swagger UI中multipart/form-data嵌套对象显示为JSON而非表单字段问题

云上老周

2026-7-21

求助：multipart/form-data请求的嵌套对象在Swagger UI中显示为JSON输入框而非表单字段

环境信息

OpenAPI版本：3.0.3
Java环境：Java 8
依赖：springdoc-openapi-ui 1.7.0

问题描述

我在定义multipart/form-data类型的POST请求时，请求体里的嵌套对象在Swagger UI的「Try it out」功能中显示为JSON输入框，而非预期的表单字段。这个问题仅在multipart请求包含嵌套对象时触发，我在Swagger UI的GitHub问题库中没找到解决方案，特来求助。

相关代码

OpenAPI定义

openapi: 3.0.3
info:
    title: 'My API'
    version: 3.0.0
servers: []
paths:
    /api_app:
        post:
            operationId: apiAppCreate
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            $ref: '#/components/schemas/ApiAppCreateRequest'
            responses:
                '200':
                    description: 'success'
                    content:
                        application/json:
                            schema: {}
components:
    schemas:
        ApiAppCreateRequest:
            properties:
                oauth:
                  type: object
                  properties:
                      callback_url:
                          type: string
                          example: 'https://example.com/oauth'
                      scopes:
                          type: array
                          items:
                              type: string
                          example:
                              - basic_account_info
                              - request_signature
            type: object

Maven依赖配置

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>