fix: [OpenAPI] Pin file upload parameter to File type

[rpanackal]

Context

• https://github.com/SAP/ai-sdk-java-backlog/issues/391

On file uploads, the remote service may expect (here Prompt Registry) Content-Disposition header to contain the filename. At the moment, setting <typeMappings>File=byte[]<typeMappings> can replace all occurrence of File type with byte[].

This means on upload operations, we end up losing filename information, critical for correct successful response.

Feature scope:

• Pin the parameter type to File in upload operation
  • Unmodifiable with <typeMappings>File=byte[]<typeMappings> override. Now only influence return type on download operations.

This is a breaking change.

Definition of Done

• Functionality scope stated & covered
• Tests cover the scope above
• Error handling created / updated & covered by the tests above
• Documentation updated
• Release notes updated

[rpanackal]

Here is a viable alternate proposal due to the existence of <typeMappings>File=byte[]<typeMappings>

Current: We pin upload type and allows typeMappings to choose download type

Alternate: We pin download type to byte[] and allow typeMappings to override upload type

I don't see a particular winner. So, any ideas are welcomes

[rpanackal]

Why not simply keep upload parameter and download return type as File?

From earlier discussions, we want to avoid placing the expectation on user to handle downloaded files properly.
Related Comment

[rpanackal]

Here is a viable alternate proposal due to the existence of <typeMappings>File=byte[]<typeMappings>

Current: We pin upload type and allows typeMappings to choose download type

Alternate: We pin download type to byte[] and allow typeMappings to override upload type

I don't see a particular winner. So, any ideas are welcomes

Nevermind. Pinning return type to byte[] in the alternate design is not feasible. There is no available isFile or isReturnFile flag on define a conditional logic in mustache file.

[newtork]

(Major/Question)

Are you saying this will no longer have an effect?

(openapi-api-apache-sample/pom.xml)

<typeMappings>File=byte[]</typeMappings>

Sounds like a regression to me.

[rpanackal]

Setting <typeMappings> is effective for download operations to change return type from File to byte[]. But not in upload operation.

The default behaviour has always been (is still) File type on method parameter and return type. In prompt registry, we overrid this behaviour using <typeMappings> . So, for our regular user, nothing changes. Still, advanced users are affected.

If that is not acceptable, we will have to go with introducing a new feature flag.