我们尝试使用swagger 2.0(OAS3)来记录Restful API，用Java实现并基于Apache CXF(jaxrs) . 对于一些尚未实现的API调用，带有swagger的文档工作正常，但是下面的Post-Request让我苦苦挣扎：

@POST

@Path("/documents")

@Consumes("multipart/mixed")

Response createDocument(

@RequestBody(description = "RestDocumentParams (required), InputStream and RelationshipParams",

content = { @Content(mediaType = "multipart/mixed", schema = @Schema(implementation = RestDocumentParams.class)),

@Content(mediaType = "application/octet-stream", schema = @Schema(type = "string", format = "binary")),

@Content(mediaType = "application/json", schema = @Schema(implementation = RelationshipParams.class)) })

@Multipart(value = "doc", type = MediaType.APPLICATION_JSON)

RestDocumentParams documentParams,

@Multipart(value = "file", type = MediaType.APPLICATION_OCTET_STREAM, required = false)

InputStream inputStream,

@Multipart(value = "rela", type = MediaType.APPLICATION_JSON, required = false)

RelationshipParams relationshipParams)

此方法应至少使用RestDocumentParams中给出的数据创建一个新Document . Optionaly可以提供文件对象(InputStream)和其他MetaData(RelationshipParams) . 必须在RequestBody中提供所有这些有效负载 .

在testframework(例如，restassured)中使用此方法可以正常工作 . 我的问题是，我如何使用swagger-annotation正确地注释这个方法，以便在Swagger-UI中使用它 .

使用上面的RequestBody-Annotation似乎不是正确的方法！在Swagger-UI中，在RequestBody的描述中出现一个组合框，让我选择三种不同的媒体类型 . 但是，如果我想尝试此方法并编辑其中一个输入参数(例如输入文件名)并选择下一个媒体类型，则最后一次编辑将丢失 .

比较此方法的requestBody的json-Strukture与"multipart content"的OAS3定义不同 . 关于OAS3定义，requestBody应该如下所示：

requestBody:

description: 'RestDocumentParams (required), InputStream and RelationshipParams'

content:

multipart/form-data:

schema:

properties:

docParams:

$ref: '#/components/schemas/RestDocumentParams'

relaParams:

$ref: '#/components/schemas/RelationshipParams'

fileName:

type: string

format: binary

但我不知道如何指定requestBody(使用swagger annotoations)来实现看起来像这样的结构 .