在 Springdoc 中表示表单数据和返回字节数组的问题

Question

我有如下一段代码，

@PostMapping(value = "/create/{userId}", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<Object> saveFile(
        @Parameter(description = "ID of the user") @PathVariable(value = "userId") final String userId,
        @Parameter(description = "Avatar of the user", content = @Content(mediaType = MediaType.APPLICATION_OCTET_STREAM_VALUE)) @RequestParam(value = "avatar", required = true) final MultipartFile file
) {
    ...
}

@GetMapping(value = "/get", produces = MediaType.IMAGE_PNG_VALUE)
@ApiResponse(responseCode = "200", description = "OK", content = {@Content(array = @ArraySchema(schema = @Schema(implementation = Byte.class)))})
public ResponseEntity<byte[]> getFile() {
    ...
}

以下是预期结果和实际结果。

如何达到预期的效果？预期结果来自Springfox。

Answer 1

对于文件格式，规范中的非类型字节。你应该发送 type: string, format: binary.

https://swagger.io/docs/specification/describing-request-body/file-upload/

因此，您的 post 方法的 requestBody 是正确的。

要在您的POST方法中描述return类型的字节数组，您可以添加以下描述：

@ApiResponse(content = @Content(schema = @Schema(type = "string", format = "binary")))

Answer 2

上周我遇到了同样的问题。我的解决方案是通过 SpringDocUtils 将 return 类型 byte-Array 替换为 String:

import org.springframework.context.annotation.Configuration;
import org.springdoc.core.SpringDocUtils;

@Configuration
public class OpenApiConfiguration {

    static {
        SpringDocUtils.getConfig()
                        .replaceWithClass(byte[].class, String.class);
    }
}

对我来说，这种方法的优点是每个 byte[] 都将替换为 String 表示形式，因此不需要通过 @ApiResponse 进行相应的显式注释。但我认为这取决于用例。

在 Springdoc 中表示表单数据和返回字节数组的问题

Problem representing form-data and returning array of byte in Springdoc

spring-mvc

springdoc