Spring中@RequestPart的OpenAPI契约编写：ParameterIn取值疑问

我正尝试为项目添加OpenAPI，以在BaseURL暴露Swagger接口。以下是我的请求映射代码：

@PostMapping(path = "/{referenceId}")
public Mono<DocumentUploadResponse> upload(
        @PathVariable(value = "referenceId") String referenceId,
        @RequestPart(value = "documents") List<FilePart> document,
        @RequestPart(value = "documentsMetaData") DocumentMetaDataApplicationRequest documentMetaDataApplicationRequest) {

    return documentStorageService.upload(referenceId, document, documentMetaDataApplicationRequest);
}

以下是我正在编写的API契约代码：

parameters = {
                @Parameter(
                        in = ParameterIn.PATH,
                        name = "referenceId",
                        description = "unique Id provided by consumer application, against which documents are stored for respective bookings"),
                @Parameter(
                        in = ***? what to write here for my @RequestPart?***
                        name = "documents",
                        description = "The number of the booking."),
                @Parameter(
                        in = **? what to write here for my @RequestPart?**
                        name = "documentsMetaData",
                        description = "The number of the booking."
        })

请问对应@RequestPart的@Parameter注解中，in参数应使用什么值，而非ParameterIn.PATH？

答案： #

对应@RequestPart的@Parameter注解，in参数应该使用ParameterIn.FORM。

@RequestPart用于接收multipart/form-data请求里的各个独立部分，在OpenAPI规范中这类参数归类为表单参数，正好对应ParameterIn.FORM枚举值。

修正后的API契约代码示例：

parameters = {
        @Parameter(
                in = ParameterIn.PATH,
                name = "referenceId",
                description = "unique Id provided by consumer application, against which documents are stored for respective bookings"),
        @Parameter(
                in = ParameterIn.FORM,
                name = "documents",
                description = "上传的文件列表"), // 建议替换为准确的描述文本
        @Parameter(
                in = ParameterIn.FORM,
                name = "documentsMetaData",
                description = "文件对应的元数据信息" // 建议替换为准确的描述文本
        )
}

额外提示：如果使用的是SpringDoc（适配OpenAPI 3.x），其实很多场景下无需手动编写@Parameter，框架会通过@RequestPart的元数据自动生成对应的OpenAPI文档；但如果需要自定义参数描述等信息，手动指定ParameterIn.FORM是正确的做法。

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