REST - 创建相同资源的多个输入答案

【问题标题】：REST - multiple input to create same resourceREST - 创建相同资源的多个输入
【发布时间】：2022-01-22 20:01:14
【问题描述】：

我正在建模 REST api 集来管理资源（例如：人）。我需要公开创建 Person 的能力：

在正文负载中提供数据：POST /Person body:{name:"John", surname:"Doe"}
通过文件将数据作为 multipart/form-data 提供：POST /Person multipart/form-data {@FormDataParam("file") InputStream uploadInputStream, @FormDataParam("file") FormDataContentDisposition fileDetail}

这意味着两个 API 的 HTTP 动词 + 路径相同。现在，如果我尝试生成 OpenAPI 3.0 文档，我将失败，因为 http + 路径必须是唯一的。

什么是REST方式来建模这两种创建资源的方式？

之后，棘手的部分，在我的两个 jersey2 端点下方：

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@Operation( tags = {"Import"},
            summary = "Import from file path",
            responses = {
                    @ApiResponse(responseCode = "202", description = "Import accepted",
                        content = @Content(mediaType = MediaType.APPLICATION_JSON, schema = @Schema(implementation = ImportRepresentation.class))),
            })
    public Response importFromFilePath(@RequestBody( description = "Import from file path", required = true,
            content = @Content(schema = @Schema(implementation = ImportFileRequest.class))) ImportFileRequest importFileRequest)
            {

.......
        return response;
    }

    @POST
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    @Produces(MediaType.APPLICATION_JSON)
    @Operation( tags = {"Import"},
                summary = "Import provided file",
                responses = {
                    @ApiResponse(responseCode = "202", description = "Import accepted",
                            content = @Content(mediaType = MediaType.APPLICATION_JSON, schema = @Schema(implementation = ImportRepresentation.class))),
            })
    public Response importUploadedFile(
            @Parameter(schema = @Schema(type = "file", format = "binary", description = "file"))
            @FormDataParam("file") InputStream uploadedInputStream,

            @Parameter(hidden = true)
            @FormDataParam("file") FormDataContentDisposition fileDetail,

            @Parameter(schema = @Schema(implementation = String.class), required = false)
            @FormDataParam("commitMessage") String commitMessage)
            {

        ........

            return response;
    }

如何注释它们以生成带有两个 requestBody.content 条目的 OpenAPI.yaml？

【问题讨论】：

标签： rest post resources

【解决方案1】：

什么是REST方式来建模这两种创建资源的方式？

就REST而言，在这两种情况下使用相同的HTTP方法和目标URI是好的。

在网络上，这可能看起来像两种不同的 HTML 表单；一种带有输入控件的表单用于收集姓名和姓氏，另一种带有用于复制文件的输入控件。在这两种情况下，提交表单都会导致浏览器向表单本身描述的目标 URI 生成 POST 请求（即：form.action）。

根据 OpenApi 3.0.3 规范，描述此方法的处理方法是单个方法和目标 URI，但在 requestBody.content 映射中具有多个媒体类型条目。请参阅 OpenAPI specification 中描述 Request Body Object 和 Media Type Object 的部分。

【讨论】：

谢谢！我用另一个主题更新了这个问题，操作注释相关。
"我如何注释它们以生成带有两个 requestBody.content 条目的 OpenAPI.yaml？" - 我的想法...？这本身就是一个非常好的问题，您可能应该将其分开。我不知道答案可能是什么。
为了检查 OpenAPI.yaml 语法与 requestBody.content 中的两个条目（application/json 和 multipart/form-data），我尝试从中生成服务器代码并生成接口（jersey2）只有一种方法接受“application/json”方式，与“multipart/form-data”无关。现在我不确定 OpenAPI 语法是否正确。我在那里拆分注释请求：link
更新：看起来 OpenAPI.yaml 语法很好，requestBody:content 中有多个条目。 OpenAPI 生成器为客户端生成 2 api，但现在可以为 jersey 2 服务器管理它。
所以这是一个非常好的问题，您也许可以提供答案。甜蜜。