[REQ][Java][Retrofit2] Preserve response headers for binary file responses with declared headers

Is your feature request related to a problem? Please describe.

I am generating a Java Retrofit2 client with RxJava3 for endpoints that return downloadable files.

The OpenAPI response declares both:

• a binary response body
• response headers such as Content-Disposition

However, the generated Retrofit2 method returns Observable<ResponseBody>. This allows reading the file body, but client code cannot access response headers such as Content-Disposition, which are needed to determine the downloaded filename.

Environment:

• OpenAPI Generator Maven Plugin: 7.14.0
• Generator: Java client, Retrofit2 library
• Library: retrofit2
• useRxJava3: true
• Retrofit: 3.0.0
• Retrofit RxJava3 adapter: 3.0.0
• OkHttp: 5.1.0
• Java: 25
• OpenAPI spec generated with Springdoc 2.8.13 / Swagger Core 2.2.36

Minimal OpenAPI response example:

responses:
  "200":
    description: OK
    headers:
      Content-Disposition:
        schema:
          type: string
    content:
      application/octet-stream:
        schema:
          type: string
          format: binary

The generated method currently looks like this:

@GET("/files/export")
Observable<ResponseBody> exportFile();

With this signature, the caller can consume the file body but cannot access Content-Disposition.

Describe the solution you'd like

I would like the Java Retrofit2 generator to optionally preserve response headers for binary file responses when response headers are declared in the OpenAPI spec.

For example, when an operation is both a file response and has response headers, the generated method could return:

@Streaming
@GET("/files/export")
Observable<Response<ResponseBody>> exportFile();

This would allow client code to access both:

response.body();
response.headers().get("Content-Disposition");

To avoid breaking existing generated clients, this could be controlled by a generator option, for example:

wrapFileResponseWithResponseWhenHeadersPresent: true

or a similar opt-in option.

Describe alternatives you've considered

As a workaround, I added a custom Java/libraries/retrofit2/api.mustache template override.

The custom template changes the return type only when both conditions are true:

• the operation is a file response
• the response declares headers

In that case it generates Observable<Response<ResponseBody>> instead of Observable<ResponseBody>, and also adds @Streaming for file responses.

This works, but copying and maintaining the whole api.mustache template creates template drift risk whenever OpenAPI Generator is upgraded.

Additional context

This issue seems specific to generated Java Retrofit2 client code rather than the OpenAPI specification itself. The OpenAPI document already contains the binary response schema and the Content-Disposition response header.

Question for maintainers:

Would you consider accepting a PR that adds an opt-in Java Retrofit2 generator option to wrap file responses with retrofit2.Response<ResponseBody> when response headers are declared?

Also, should @Streaming be generated for file responses in the Java Retrofit2 library?

Start with Java/libraries/retrofit2/api.mustache, comparing the existing file-response return type with the conditional behavior described in the issue. Determine how an opt-in option should affect operations that declare both binary content and response headers; done means generated clients can access the body and headers without changing existing defaults.