Java+Apache CXF下OAS3的multipart请求RequestBody正确Swagger注解咨询

针对你遇到的POST请求（multipart/mixed类型）的Swagger注解问题，结合Apache CXF和OpenAPI 3的规范，我整理了正确的注解写法和关键要点：

完整代码示例 #

@POST
@Path("/documents")
@Consumes("multipart/mixed")
@Operation(summary = "创建文档", description = "通过multipart混合请求提交文档参数、文件流及关系信息")
@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "文档创建成功"),
    @ApiResponse(responseCode = "400", description = "请求参数无效或缺失")
})
@RequestBody(
    description = "请求包含三个部分：必填的RestDocumentParams、必填的文档流InputStream，以及可选的RelationshipParams",
    required = true,
    content = @Content(
        mediaType = "multipart/mixed",
        schema = @Schema(type = "object", properties = {
            // 文档参数部分
            @Schema(
                name = "documentParams",
                description = "文档基础参数（必填）",
                required = true,
                implementation = RestDocumentParams.class
            ),
            // 文件流部分
            @Schema(
                name = "documentContent",
                description = "文档内容二进制流（必填）",
                required = true,
                type = "string",
                format = "binary"
            ),
            // 关系参数部分
            @Schema(
                name = "relationshipParams",
                description = "文档关联关系参数（可选）",
                implementation = RelationshipParams.class
            )
        })
    )
)
Response createDocument(
    @Part("documentParams") RestDocumentParams documentParams,
    @Part("documentContent") InputStream documentContent,
    @Part("relationshipParams") RelationshipParams relationshipParams
);

关键要点说明 #

• JAX-RS参数绑定：处理multipart请求必须用@Part注解标注每个方法参数，每个@Part的value对应multipart请求中part的名称，确保请求体的各个部分能正确映射到方法参数。
• Swagger请求体定义：
  • @RequestBody的content指定mediaType = "multipart/mixed"，明确请求类型。
  • 内部schema定义为type = "object"，每个属性对应一个multipart part，通过name和请求中的part名称对应。
  • 对于InputStream类型的文件流，需要设置type = "string"和format = "binary"，这样Swagger UI会自动渲染文件上传控件。
  • 用required = true标记必填的part，确保文档能清晰展示参数的必填性。
• 依赖兼容性：确保你的项目使用的是支持OpenAPI 3的Swagger依赖（比如io.swagger.core.v3:swagger-jaxrs2 2.x及以上版本），同时Apache CXF的版本要和Swagger集成兼容。

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