如何配置Swagger UI使其支持接收包含可选字段的请求体

Swagger（OpenAPI）完全支持可选字段的配置，具体实现方式如下：

核心实现逻辑 #

OpenAPI的Schema对象支持通过required顶层属性声明必填字段列表，所有未出现在该列表中的字段默认即为可选字段，符合你只在请求携带app字段时才存储的需求。

修改后的配置示例 #

你只需要在现有的Project Schema中补充required数组即可，修改后代码如下：

post: {
    summary: 'Create a new project',
    tags: ['projects'],
    requestBody: {
        content: {
            'application/json': {
                schema: {
                    $ref: '#/components/schemas/Project'
                }
            }
        }
    }
},
components: {
    schemas: {
        Project: {
            type: 'object',
            // 声明必填字段，未列入的app字段自动为可选
            required: ["name", "description", "github", "logo"],
            properties: {
                name: {
                    type: 'string'
                },
                description: {
                    type: 'string'
                },
                github: {
                    type: 'string'
                },
                logo: {
                    type: 'string'
                },
                app: {
                    type: 'string',
                    description: "可选字段，仅请求携带时存入数据库"
                }
            }
        }
    }
}

额外说明 #

• 配置完成后Swagger UI会自动为必填字段标注*号，可选字段无标识，生成的请求示例也会明确提示app为可选项。
• 如果需要允许app字段传入null值，可以在app的属性配置中新增nullable: true即可。

内容的提问来源于stack exchange，提问作者João Casarin