Returning StreamedFile does not fulfill OpenAPI specs

[debuglevel]

A controller function returning a StreamedFile does not generate a OpenAPI.yml according to the OpenAPI 3.0 specs. It instead describes the fields etc of the StreamedFile class.

Steps to Reproduce

    @Produces("application/pdf")
    @Get("/{documentId}")
    fun getOne(documentId: UUID): HttpResponse<StreamedFile> {
        [...]

Expected Behaviour

The OpenAPI Specs specifies files like this:

  /v1/documents/{documentId}:
    get:
      [...]
      default:
        description: getOne default response
        content:
          application/pdf:
            schema:
              type: string
              format: binary

Actual Behaviour

The code above produces this OpenAPI.yml

  /v1/documents/{documentId}:
    get:
      [...]
      responses:
        default:
          description: getOne default response
          content:
            application/pdf:
              schema:
                $ref: '#/components/schemas/StreamedFile'

Environment Information

• Micronaut Version: 2.1
• JDK Version: 1.8

[swaechter]

I am not sure how related my problem is, but it also generats a wrong schema for SystemFile (With SystemFile instead of StreamedFile). Micronaut version is 2.3.0.

The code bellow fixed my problem (@produces doesn't fix the problem) + Just switch the MediaType if required e.g. for PDFs:

/**
 * Download a specific log file by the file name.
 *
 * @param fileName Name of the log file
 * @return Log file as download
*/
@Get("/logs/files/file")
@Tag(name = "Logs")
@ApiResponse(responseCode = "200", description = "Download of the specific log file", content = @Content(mediaType = MediaType.APPLICATION_OCTET_STREAM, schema = @Schema(type = "string", format = "binary")))
@ApiResponse(responseCode = "401", description = "Not authenticated")
@ApiResponse(responseCode = "500", description = "Internal server error")
public SystemFile downloadLogFile(@QueryValue String fileName) {
    return logService.downloadLogFileByFileName(fileName);
}

[debuglevel]

Thanks @swaechter, I did not think of explicitly using annotations to describe the API 😅

[debuglevel]

In case anybody needs the Kotlin variant of @swaechter's Java code:

    @Produces("application/pdf")
    @Get("/{documentId}")
    @ApiResponse(responseCode = "200", description = "foo", content = [Content(mediaType = MediaType.APPLICATION_OCTET_STREAM, schema = Schema(type = "string", format = "binary"))]
    fun getOne(documentId: UUID): HttpResponse<StreamedFile> {
       [...]

[swaechter]

@debuglevel Small addendum: When you have an endpoint where you upload a file and return it as file download (Maybe you do this in your LiberatePDF2 project), you have to set the produces field in the POST/PUT annotation. Otherwise Micronaut will generate a really strange 403 Forbidden error when you trigger the endpoint via Swagger UI:

@Post(value = "/signing/file", consumes = MediaType.MULTIPART_FORM_DATA, produces = MediaType.APPLICATION_OCTET_STREAM) // This line is really important, otherwise the 200 annotation will trigger a 403 Forbidden
@Tag(name = "Signing")
@ApiResponse(responseCode = "200", description = "Download the signed file", content = @Content(mediaType = MediaType.APPLICATION_OCTET_STREAM, schema = @Schema(type = "string", format = "binary")))
@ApiResponse(responseCode = "401", description = "Not authenticated")
@ApiResponse(responseCode = "500", description = "Internal server error")
public SystemFile signFile(CompletedFileUpload file) throws ServerException {
    return signingService.signFile(file);
}