Question

我们尝试使用 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 中提供的数据创建新文档。 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）来实现看起来像这样的结构。

这个requestBody的正确swagger-annotation是什么？

0 个答案: