Swagger YAML配置中PATCH请求必填字段校验异常问题

• 原项目通过控制器的@Swagger注解生成接口文档一切正常，切换为YAML配置文件统一管理后，除GET、PATCH外的请求均报错提示模型属性为必填项
• 以PATCH请求为例：数据库模型中isDeleted字段默认值为false且设为必填，调用接口时需将该字段改为true，但Swagger UI始终提示该字段必填；将YAML中required设为false可正常调用，但违背业务需求
• Postman调用该接口完全正常，仅Swagger UI存在校验异常

相关截图说明 #

• Swagger界面：PATCH请求的参数区域中，isDeleted字段被标记为必填项
• 错误响应：Swagger UI返回错误提示"isDeleted is required"，即使请求体中已传入该字段

OpenAPI 3.0规范已废弃parameters节点中in: body的写法，改用requestBody节点定义请求体内容。原YAML仍使用旧格式，导致Swagger UI的校验逻辑异常，无法正确识别模型的默认值和必填规则。

修改YAML接口文档，将请求体定义从parameters迁移到requestBody，并同步模型的必填规则：

修改后的YAML代码 #

paths:
    /api/order/deleteOrder/{orderId}:
        patch:
            tags:
                - Order
            summary: change the status of a certain order
            produces:
                - application/json
            security:
                - bearerAuth: []
            parameters:
                - name: orderId
                  in: path
                  description: path parameter takes the order id to be deleted
                  required: true
                  schema:
                      type: string
                      example: 6352e63e29c4c5439a435d56
            # 替换原in: body参数为标准requestBody定义
            requestBody:
                description: will change the order status from false to true 
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/definitions/deleteOrder'
            responses:
                200:
                    description: successfull operation
                    content:
                        application/json:
                            schema:
                                $ref: '#/definitions/sucesssDeleteOrderResponse'

                500:
                    description: Unsuccessfull operation
                    content:
                        application/json:
                            schema:
                                $ref: '#/definitions/FailureDeleteOrderResponse'

definitions:
    deleteOrder:
        type: object
        properties:
            isDeleted:
                type: boolean
                default: false  # 与数据库模型默认值同步
        required:
            - isDeleted  # 明确标记字段为必填，与模型规则一致

    sucesssDeleteOrderResponse:
        type: object
        properties:
            message:
                type: string
                default: 'Orders status changed successfully'
            statut:
                type: number
                default: 200

    FailureDeleteOrderResponse:
        type: object
        properties:
            message:
                type: string
                default: 'Failed to change status order'
            statut:
                type: number
                default: 500

关键修改点说明 #

1. 请求体定义标准化：移除parameters中in: body的旧格式，改用OpenAPI 3.0标准的requestBody节点定义请求体
2. 必填规则同步：在deleteOrder定义中添加required: [- isDeleted]，与数据库模型的required: true规则保持一致，让Swagger UI正确识别必填字段
3. 默认值同步：在YAML的schema中添加default: false，与模型默认值对应，提升文档准确性

修改后重启服务，在Swagger UI中测试PATCH请求：

• 填写orderId和isDeleted: true后可正常发送请求，无错误提示
• 若未填写isDeleted字段，Swagger UI会正确提示该字段为必填，符合业务规则

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