[#520] Fix OpenAPI generated routes response contract

[armanist]

Closes #520

Summary by CodeRabbit

• Bug Fixes
  • Fixed OpenAPI route generation to properly return Response objects, resolving undefined variable issues in the documentation and specification endpoints.

[coderabbitai]

📝 Walkthrough

Walkthrough

The OpenAPI installer command's route generator is updated to emit compliant route closures. The docs and spec endpoints now return Response objects directly through response()->html(...) and response()->json(...) helpers, eliminating undefined variable issues in generated code.

Changes

OpenAPI Route Generator Response Contract Fix

Layer / File(s)	Summary
Route generation Response contract update src/Console/Commands/OpenApiCommand.php, CHANGELOG.md	The generated docs and spec route handlers are refactored to use closures without a $response parameter, returning Response objects directly via response()->html(...) and response()->json(...) instead of calling methods on an undefined variable. Changelog entry documents the fix for undefined response-variable usage.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• softberg/quantum-php-core#499: Updates generated OpenAPI route handlers to return response()->json(...)/response()->html(...) directly, ensuring proper Response contract compliance alongside controller/template migration.
• softberg/quantum-php-core#475: Enforces dispatcher validation that route/closure handlers return a Response object, providing the contract enforcement that this PR's generated code now satisfies.

Suggested labels

bug

Suggested reviewers

• andrey-smaelov

Poem

🐰 A route once broken, undefined and bare,
Now springs response() helpers through the air,
No phantom $response to cause dismay,
Just html() and json() save the day! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically references issue #520 and accurately describes the main change: fixing OpenAPI generated routes to comply with the Response return contract.
Linked Issues check	✅ Passed	All acceptance criteria from #520 are met: generated closures use response() helpers, return Quantum\Http\Response instances, and eliminate undefined variable usage.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the OpenAPI route generator response contract issue. CHANGELOG.md and OpenApiCommand.php modifications align with issue #520 requirements.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.87%. Comparing base (5710161) to head (7db6e0c).

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #521   +/-   ##
=========================================
  Coverage     90.87%   90.87%           
  Complexity     3070     3070           
=========================================
  Files           263      263           
  Lines          8100     8100           
=========================================
  Hits           7361     7361           
  Misses          739      739           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

🧹 Nitpick comments (1)

src/Console/Commands/OpenApiCommand.php (1)

199-202: ⚡ Quick win

Consider error handling for missing or invalid spec.json.

The generated spec endpoint calls $fs->getJson(...) which may throw or return unexpected data if the spec file doesn't exist or contains invalid JSON. While the spec.json is generated during installation, consider whether the route should handle potential read failures gracefully (e.g., after manual file deletion or permissions issues).

🛡️ Suggested enhancement with error handling

         $route->get("spec", function (): Quantum\Http\Response {
             $fs = Quantum\Storage\Factories\FileSystemFactory::get();
-            return response()->json($fs->getJson(modules_dir() . "' . DS . $module . DS . 'resources' . DS . 'openapi' . DS . 'spec.json"));
+            $specPath = modules_dir() . "' . DS . $module . DS . 'resources' . DS . 'openapi' . DS . 'spec.json";
+            if (!$fs->exists($specPath)) {
+                return response()->json(["error" => "OpenAPI specification not found"], 404);
+            }
+            return response()->json($fs->getJson($specPath));
         });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/Console/Commands/OpenApiCommand.php` around lines 199 - 202, The spec
route closure currently calls $fs->getJson(...) and returns
response()->json(...) without handling missing files or JSON errors; update the
Route (the anonymous function registered for "spec") to wrap the $fs->getJson
call in a try/catch (or check file existence/valid JSON beforehand), return an
appropriate JSON error response with a 404 or 500 status when the file is
missing/unreadable/invalid, and ensure the success path still returns the parsed
spec via response()->json; reference the route closure, $fs->getJson,
modules_dir() and response()->json when making the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/Console/Commands/OpenApiCommand.php`:
- Around line 199-202: The spec route closure currently calls $fs->getJson(...)
and returns response()->json(...) without handling missing files or JSON errors;
update the Route (the anonymous function registered for "spec") to wrap the
$fs->getJson call in a try/catch (or check file existence/valid JSON
beforehand), return an appropriate JSON error response with a 404 or 500 status
when the file is missing/unreadable/invalid, and ensure the success path still
returns the parsed spec via response()->json; reference the route closure,
$fs->getJson, modules_dir() and response()->json when making the change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d82fcb72-ab4e-4b40-ace4-9854ea8e67d7

📥 Commits

Reviewing files that changed from the base of the PR and between 5710161 and 7db6e0c.

📒 Files selected for processing (2)

• CHANGELOG.md
• src/Console/Commands/OpenApiCommand.php