Update to return HttpResponseMessage for file downloads

[frogcrush]

As discussed in #507, determine common file responses and generate HttpResponseMessage instead of an empty IApiResult.

Summary by CodeRabbit

• New Features

  • Generated APIs now automatically detect file/binary responses and return HttpResponseMessage for octet-streams, images, PDFs, archives, audio/video and similar content types; XML docs updated to describe this behavior.
  • Recognizes HttpResponseMessage as an API-like response when relevant; form-url-encoded submissions remain unaffected.

• Tests

  • Added tests confirming generation and successful build of code for file-stream scenarios, including positive and negative cases and option-driven behavior.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

📝 Walkthrough

Walkthrough

Adds detection of file/binary responses in the code generator. Operations with binary content types or file-like schemas now produce HttpResponseMessage return types. New private helpers classify file content types and responses; no public API signatures changed.

Changes

Cohort / File(s)	Summary
File Stream Response Handling src/Refitter.Core/RefitInterfaceGenerator.cs	Added IsFileStreamResponse(OpenApiOperation) and IsFileContentType(string) helpers; updated GetTypeName() to short‑circuit to HttpResponseMessage for detected file responses; extended IsApiResponseType(string) to accept `(Task
Tests: File Stream Responses src/Refitter.Tests/Examples/FileStreamResponseTests.cs	New test suite embedding an OpenAPI spec with endpoints returning application/octet-stream, image/*, application/pdf, and a form endpoint. Tests assert generated methods use HttpResponseMessage for binary responses, exclude form‑url‑encoded, validate build, and check ReturnIApiResponse behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I sniff the bytes and hop with glee,
Streams turned responses, tidy and free,
PDFs, images, octets in tow,
I nudge the generator where to go,
A rabbit's cheer for safer flow 🥕📦

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: adding logic to detect file/binary responses and return HttpResponseMessage for file downloads instead of empty IApiResult.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/Refitter.Core/RefitInterfaceGenerator.cs`:
- Around line 166-181: The file-detection logic uses response.Schema which can
be the schema of a different content type when multiple content types exist;
instead iterate the response.Content entries and for each matching file
content-type (use the existing StartsWith checks but exclude
"application/x-www-form-urlencoded" rather than matching all "application/x-"),
capture that specific content entry's schema (e.g., the media type's Schema) and
use it to determine binary/file type (check schema.Format == "binary" or
schema.Type == JsonObjectType.File) and return true; update the check around the
"application/x-" prefix to exclude "application/x-www-form-urlencoded" so form
data is not treated as file content.

🧹 Nitpick comments (2)

src/Refitter.Tests/Examples/FileStreamResponseTests.cs (2)

115-120: Consider adding a clarifying comment or renaming the test.

The test verifies that HttpResponseMessage is returned even when ReturnIApiResponse is enabled, which is the expected behavior. However, the test name could be clearer about this intentional bypass.

✨ Suggested improvement

     [Test]
-    public async Task Generates_HttpResponseMessage_With_IApiResponse_Setting()
+    public async Task Generates_HttpResponseMessage_Even_When_ReturnIApiResponse_Is_Enabled()
     {
         string generatedCode = await GenerateCode(returnIApiResponse: true);
+        // File downloads should return HttpResponseMessage directly, bypassing IApiResponse wrapping
         generatedCode.Should().Contain("Task<HttpResponseMessage> DownloadFile(string fileId");
     }

---

122-134: Consider adding test coverage for IObservable mode.

The generator supports ReturnIObservable which would produce IObservable<HttpResponseMessage> instead of Task<HttpResponseMessage>. Adding a test for this mode would improve coverage.

✨ Example additional test

[Test]
public async Task Generates_IObservable_HttpResponseMessage_When_ReturnIObservable_Is_Enabled()
{
    var swaggerFile = await SwaggerFileHelper.CreateSwaggerFile(OpenApiSpec);
    var settings = new RefitGeneratorSettings
    {
        OpenApiPath = swaggerFile,
        ReturnIObservable = true
    };

    var sut = await RefitGenerator.CreateAsync(settings);
    var generatedCode = sut.Generate();
    
    generatedCode.Should().Contain("IObservable<HttpResponseMessage> DownloadFile(string fileId");
}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/Refitter.Core/RefitInterfaceGenerator.cs`:
- Around line 152-173: The IsFileStreamResponse method misses media types that
have no Schema and thus won't be detected as file responses; update
IsFileStreamResponse to treat content entries whose Schema is null as file
streams for appropriate content types by adding a fallback check after
retrieving var schema = contentEntry.Value?.Schema — if schema is null and
IsFileContentType(contentEntry.Key) (optionally also ensure the content type is
not a vendor JSON like application/vnd* if you want to exclude those), return
true so responses with schema-less file media types map to HttpResponseMessage;
keep the existing binary/Type checks (schema.Format == "binary" || schema.Type
== JsonObjectType.File) and only use the schema-null fallback when those are
absent.

In `@src/Refitter.Tests/Examples/FileStreamResponseTests.cs`:
- Around line 125-131: The presence check uses the wrong casing: update the
assertion in the test Does_Not_Generate_HttpResponseMessage_For_FormUrlEncoded
to look for "SubmitForm" (PascalCase) or perform a case-insensitive containment
check on generatedCode so it matches the generator's PascalCase method names;
ensure the assertion that checks for the absence of "Task<HttpResponseMessage>
SubmitForm(" still references SubmitForm with correct casing.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Handle file content types with missing schemas.
OpenAPI allows a media type without a schema; those would be treated as non-file here. If you want schema-less file responses to map to HttpResponseMessage, add a fallback (optionally excluding application/vnd* if you want to keep vendor JSON strict).

💡 Possible fallback

                 if (IsFileContentType(contentEntry.Key))
                 {
                     var schema = contentEntry.Value?.Schema;
-                    if (schema?.Format == "binary" || schema?.Type == NJsonSchema.JsonObjectType.File)
+                    if (schema == null)
+                        return true;
+                    if (schema.Format == "binary" || schema.Type == NJsonSchema.JsonObjectType.File)
                         return true;
                 }

🤖 Prompt for AI Agents

In `@src/Refitter.Core/RefitInterfaceGenerator.cs` around lines 152 - 173, The
IsFileStreamResponse method misses media types that have no Schema and thus
won't be detected as file responses; update IsFileStreamResponse to treat
content entries whose Schema is null as file streams for appropriate content
types by adding a fallback check after retrieving var schema =
contentEntry.Value?.Schema — if schema is null and
IsFileContentType(contentEntry.Key) (optionally also ensure the content type is
not a vendor JSON like application/vnd* if you want to exclude those), return
true so responses with schema-less file media types map to HttpResponseMessage;
keep the existing binary/Type checks (schema.Format == "binary" || schema.Type
== JsonObjectType.File) and only use the schema-null fallback when those are
absent.

[Copilot]

Pull request overview

This pull request enhances Refitter to automatically detect file/binary stream responses in OpenAPI specifications and generate HttpResponseMessage return types instead of empty IApiResponse results. This addresses a common use case for file downloads and provides better type safety for binary content.

Changes:

• Added automatic detection logic for file stream responses based on content type and schema format
• Enhanced IsApiResponseType to recognize HttpResponseMessage for proper XML documentation generation
• Comprehensive test coverage for common file download scenarios including octet-stream, images, PDFs, and negative cases

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
src/Refitter.Tests/Examples/FileStreamResponseTests.cs	New test file with comprehensive coverage of file stream detection including positive cases (octet-stream, JPEG, PNG, PDF) and negative cases (form-urlencoded), plus validation that generated code builds successfully
src/Refitter.Core/RefitInterfaceGenerator.cs	Core implementation adding IsFileStreamResponse and IsFileContentType methods to detect binary responses, integrated into GetTypeName with proper precedence, and updated IsApiResponseType to handle HttpResponseMessage

[Copilot]

This foreach loop implicitly filters its target sequence - consider filtering the sequence explicitly using '.Where(...)'.

[Copilot]

This foreach loop implicitly filters its target sequence - consider filtering the sequence explicitly using '.Where(...)'.

[christianhelle]

@all-contributors please add @frogcrush for code

[allcontributors]

@christianhelle

I've put up a pull request to add @frogcrush! 🎉

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[frogcrush]

@christianhelle failing check issue doesn't seem like a code issue?

[christianhelle]

@christianhelle failing check issue doesn't seem like a code issue?

It's some concurrency issue that got introduced when I switched to TUnit (from XUnit) some time ago. I can't reproduce it locally but it happens every now and then when built from Github Actions. I actually just removed this test on the latest master

[christianhelle]

The changes look good to me and the smoke tests all pass so let's get this in

[christianhelle]

@frogcrush thank you for this contribution