OpenAPI Swagger-UI Annotation @Callback

Question

I'm trying to annotate a REST Controller with @Callback but I don't know how to define parameters.

I have a simple Dto (Lombok used) with an id, a MultipartFile and a callbackUrl :

    @Getter
    @Setter
    @FieldDefaults(level = AccessLevel.PRIVATE)
    @NoArgsConstructor
    @AllArgsConstructor
    @Builder(toBuilder = true)
    public class MyDto {
      String id;
      MultipartFile zipFile;
      String callbackUrl;
    }

Then I have this POST endpoint :

    @Operation(description = "POST test method")
    @Callback(
    callbackUrlExpression = "??????",
    name = "subscription",
    operation = {
      @Operation(
          method = "post",
          description = "payload data will be sent",
          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();
    }

This is the result :

I don't know how to define parameters part (with RequestPart) inside @Callback annotation.

Also I don't know how to use callbackUrlExpression to refer to MyDto.callbackUrl.

My target is to obtain/describe a Callback API Endpoint like this one :

    @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();
    }

Thanks and please excuse my poor English.

Answer 1

I found these docs to be helpful:

https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#callback

(Since you have more than one question and they are a bit general, I won't try to answer everything directly here.)