Generate correct openapi when returning files from controllers

Fixes #441

Author: ilopmar

openapi/build.gradle

@@ -6,6 +6,8 @@ dependencies {
     compileOnly "io.micronaut:micronaut-inject-java"
 
     implementation "io.micronaut:micronaut-http"
+    implementation "io.micronaut:micronaut-http-server"
+
     api "io.swagger.core.v3:swagger-core:$swaggerVersion"
     api "io.swagger.core.v3:swagger-models:$swaggerVersion"
     api "io.swagger.core.v3:swagger-annotations:$swaggerVersion"

openapi/src/main/java/io/micronaut/openapi/visitor/AbstractOpenApiVisitor.java

@@ -40,6 +40,7 @@
 import io.micronaut.core.util.CollectionUtils;
 import io.micronaut.core.util.StringUtils;
 import io.micronaut.http.MediaType;
+import io.micronaut.http.server.types.files.FileCustomizableResponseType;
 import io.micronaut.http.uri.UriMatchTemplate;
 import io.micronaut.inject.ast.ClassElement;
 import io.micronaut.inject.ast.Element;
@@ -79,6 +80,7 @@
 import io.swagger.v3.oas.models.media.MapSchema;
 import io.swagger.v3.oas.models.media.ObjectSchema;
 import io.swagger.v3.oas.models.media.Schema;
+import io.swagger.v3.oas.models.media.StringSchema;
 import io.swagger.v3.oas.models.security.SecurityRequirement;
 import io.swagger.v3.oas.models.security.SecurityScheme;
 import org.reactivestreams.Publisher;
@@ -690,6 +692,9 @@ private boolean isTypeNullable(ClassElement type) {
                     if (schema != null) {
                         schema = arraySchema(schema);
                     }
+                } else if (type.isAssignable(FileCustomizableResponseType.class)) {
+                    schema = new StringSchema();
+                    schema.setFormat("binary");
                 } else {
                     schema = getSchemaDefinition(openAPI, context, type, definingElement, mediaTypes);
                 }

openapi/src/test/groovy/io/micronaut/openapi/visitor/OpenApiFileResponseTypeSpec.groovy

@@ -0,0 +1,106 @@
+package io.micronaut.openapi.visitor
+
+import io.micronaut.annotation.processing.test.AbstractTypeElementSpec
+import io.swagger.v3.oas.models.OpenAPI
+import io.swagger.v3.oas.models.Operation
+
+class OpenApiFileResponseTypeSpec extends AbstractTypeElementSpec {
+    def setup() {
+        System.setProperty(AbstractOpenApiVisitor.ATTR_TEST_MODE, "true")
+    }
+
+    void "test build the OpenAPI for returning files"() {
+        when:
+        buildBeanDefinition('test.MyBean', '''
+package test;
+
+import io.micronaut.http.HttpResponse;
+import io.micronaut.http.annotation.*;
+import io.micronaut.http.server.types.files.*;
+
+import java.util.UUID;
+
+@Controller("/upload")
+class FooController {
+
+    @Produces("application/pdf")
+    @Get("/response-streamed-file/{documentId}")
+    public HttpResponse<StreamedFile> action1(UUID documentId) {
+        return null;
+    }
+    
+    @Produces("application/pdf")
+    @Get("/response-system-file/{documentId}")
+    public HttpResponse<SystemFile> action2(UUID documentId) {
+        return null;
+    }
+    
+    @Produces("application/pdf")
+    @Get("/streamed-file/{documentId}")
+    public StreamedFile action3(UUID documentId) {
+        return null;
+    }
+    
+    @Produces("application/pdf")
+    @Get("/system-file/{documentId}")
+    public SystemFile action4(UUID documentId) {
+        return null;
+    }
+}
+
+@jakarta.inject.Singleton
+class MyBean {}
+''')
+
+        OpenAPI openAPI = AbstractOpenApiVisitor.testReference
+
+        then:
+        openAPI
+        openAPI.paths.size() == 4
+        openAPI.paths.each {
+            assert it.value.get.responses.size() == 1
+            assert it.value.get.responses['200'].content['application/pdf'].schema.type == 'string'
+            assert it.value.get.responses['200'].content['application/pdf'].schema.format == 'binary'
+            assert it.value.get.responses['200'].content['application/pdf'].schema.$ref == null
+        }
+    }
+
+    void "test build the OpenAPI for returning files and check their annotations takes precedence"() {
+        when:
+        buildBeanDefinition('test.MyBean', '''
+package test;
+
+import io.micronaut.http.HttpResponse;
+import io.micronaut.http.annotation.*;
+import io.micronaut.http.server.types.files.*;
+import io.swagger.v3.oas.annotations.responses.*;
+import io.swagger.v3.oas.annotations.media.*;
+
+import java.util.UUID;
+
+@Controller("/upload")
+class FooController {
+
+    @Produces("application/octet-stream")
+    @Get("/{documentId}")
+    @ApiResponse(responseCode = "200", content = @Content(mediaType = "application/octet-stream", schema = @Schema(type = "string", format = "binary")))
+    public HttpResponse<StreamedFile> action(UUID documentId) {
+        return null;
+    }
+}
+
+@jakarta.inject.Singleton
+class MyBean {}
+''')
+
+        OpenAPI openAPI = AbstractOpenApiVisitor.testReference
+
+        then: 'The content is the one defined in the @Content annotation'
+        openAPI
+        openAPI.paths.size() == 1
+        Operation operation = openAPI.paths.get('/upload/{documentId}').get
+        operation.responses['200'].content['application/octet-stream'].schema.type == 'string'
+        operation.responses['200'].content['application/octet-stream'].schema.format == 'binary'
+        operation.responses['200'].content['application/octet-stream'].schema.$ref == null
+    }
+}