OpenAPI Swagger @Callback注解参数定义与callbackUrlExpression配置问题

1. callbackUrlExpression 关联MyDto字段 #

直接使用OpenAPI标准运行时表达式即可读取请求体中的callbackUrl字段，配置值为：
$request.body#/callbackUrl
该表达式会自动从当前请求的body中提取callbackUrl字段值作为回调请求的目标地址，适配multipart/form-data类型的请求。

2. 回调请求参数定义 #

有两种可选实现方案，按需选择即可：

方案一：直接在@Callback中内嵌参数定义 #

适合回调逻辑简单、参数较少的场景，无需额外新增代码，完整的接口代码如下：

@Operation(description = "POST test method")
@Callback(
    name = "subscription",
    callbackUrlExpression = "$request.body#/callbackUrl",
    operation = @Operation(
        method = "post",
        path = "/callback_upload",
        description = "payload data will be sent",
        requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
            required = true,
            content = @Content(
                mediaType = MediaType.MULTIPART_FORM_DATA_VALUE,
                schema = @Schema(
                    type = "object",
                    requiredProperties = {"request", "zip"},
                    properties = {
                        @Schema.Property(
                            name = "request",
                            implementation = MyRequestDto.class
                        ),
                        @Schema.Property(
                            name = "zip",
                            type = "string",
                            format = "binary"
                        )
                    }
                )
            )
        ),
        responses = {
            @ApiResponse(
                responseCode = "200",
                description = "Return this code if the callback was received and processed successfully"),
            @ApiResponse(
                responseCode = "default",
                description = "All other response codes will disable this callback subscription")
        }
    )
)
@PostMapping(
   path = "/post_test",
   consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
public ResponseEntity<Void> postTestMethod(MyDto myDto) {
  return ResponseEntity.ok().build();
}

方案二：引用独立的回调文档方法 #

适合回调参数复杂、需要频繁调整的场景，通过复用现有接口的文档定义减少冗余配置：
直接使用你已有的callbackUpload实现方法即可，SpringDoc会自动读取它的参数、请求类型等定义，不需要额外写空方法：

@Operation(summary = "回调上传接口")
@PostMapping(
  path = "/callback_upload",
  consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
public ResponseEntity<Void> callbackUpload(
  @RequestPart(name = "request") @NotNull MyRequestDto myRequestDto,
  @RequestPart(name = "zip") @NotNull MultipartFile zip)
  throws IOException {
    final var zipUploaded = File.createTempFile("zipUploaded", ".zip");
    zip.transferTo(zipUploaded);
    return ResponseEntity.ok().build();
}

然后修改原接口的@Callback配置，直接通过ref引用上述方法的文档即可：

@Operation(description = "POST test method")
@Callback(
    name = "subscription",
    callbackUrlExpression = "$request.body#/callbackUrl",
    operation = @Operation(ref = "callbackUpload")
)
@PostMapping(
   path = "/post_test",
   consumes = {MediaType.MULTIPART_FORM_DATA_VALUE})
public ResponseEntity<Void> postTestMethod(MyDto myDto) {
  return ResponseEntity.ok().build();
}

这个方案的好处是回调参数调整时只需要修改实际的回调方法，不需要同步修改@Callback里的嵌套注解，维护成本更低。

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