我们尝试使用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)来实现看起来像这样的结构 .