Issue/522 demoapi openapi coverage

[armanist]

Fixes #522

Summary by CodeRabbit

Release Notes

• Documentation

  • Improved OpenAPI API documentation with cleaner annotation structure and more complete request/response examples.
  • Standardized endpoint documentation across authentication, post, and account management routes.
  • Enhanced path parameter documentation for consistency.

• New Features

  • Added OpenAPI documentation templates for account management and comment endpoints.

[coderabbitai]

Warning

Rate limit exceeded

@armanist has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 32 minutes and 26 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 081d5270-09ba-4bb9-98de-7092afb7abbc

📥 Commits

Reviewing files that changed from the base of the PR and between b968a7f and 4e753bd.

📒 Files selected for processing (5)

• src/Console/Commands/OpenApiCommand.php
• src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
• src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
• src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
• tests/Unit/Console/Commands/OpenApiCommandTest.php

📝 Walkthrough

Walkthrough

This PR fixes incomplete and inconsistent OpenAPI templates in the DemoApi module. It corrects the spec file path construction, updates four controller OpenAPI templates (auth, post) with accurate path parameters and schemas, and introduces two new controller templates (account, comment) for previously undocumented endpoints.

Changes

OpenAPI Template and Spec Updates

Layer / File(s)	Summary
Spec file path construction fix src/Console/Commands/OpenApiCommand.php	The generated /api/spec route now correctly constructs the module's OpenAPI spec file path by properly concatenating modules_dir(), module name, and fixed resources/openapi/spec.json suffix.
Auth controller OpenAPI template updates src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl	All auth endpoints (signin, me, signout, signup, activate, forget, reset, verify, resend) are updated with corrected path parameters (token, code instead of activate_token, reset_token, otp_token), accurate request/response schemas with inline JSON examples, bearer-token security, and standardized error responses; imports now use Quantum\Http\Request.
Post controller OpenAPI template updates src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl	All post endpoints (posts, post, myPosts, create, amend, delete, deleteImage) are updated to use uuid instead of id in path parameters, add query parameters for listing (per_page, page, q), include bearer-token security, expand response examples with nested comment/author data, and standardize documented error responses (401, 422, 429, 500).
Account controller OpenAPI template src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl	New template with OpenAPI annotations for account settings endpoints: PUT /api/account-settings/update and PUT /api/account-settings/update-password, each with request/response schemas, bearer-token security, and standardized error responses.
Comment controller OpenAPI template src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl	New template with OpenAPI annotations for comment management: POST /api/comments/create/{uuid} and DELETE /api/comments/delete/{uuid}, with documented request/response schemas, bearer-token security, and error responses.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• softberg/quantum-php-core#521: Fixes the generated route closure in OpenApiCommand::openapiRoutes() to correctly return the spec response via response()->json(...).
• softberg/quantum-php-core#485: Extends PHPUnit coverage for OpenApiCommand execution paths via OpenApiCommandTest.
• softberg/quantum-php-core#489: Adds unit tests for OpenApiCommand::openapiRoutes() including validation of the expected resources/openapi/spec.json path.

Suggested labels

testing

Poem

🐰 Whiskers twitch with doc delight,
Templates fixed, paths now right,
Auth and posts and comments too,
Spec.json fresh, descriptions true,
APIs documented, clean and bright!

🚥 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 PR title clearly identifies the main work: improving DemoApi OpenAPI coverage to address issue #522, which is the primary focus of this changeset.
Linked Issues check	✅ Passed	The PR addresses all key requirements from issue #522: adds missing endpoint coverage (account, comments), fixes path parameter mismatches (token, code, uuid), documents query params, and fixes the spec route path concatenation.
Out of Scope Changes check	✅ Passed	All changes are scoped to OpenAPI template improvements and the OpenApiCommand spec route path fix, directly addressing the stated objectives with no unrelated modifications.
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.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b968a7fc34

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 2

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

Inline comments:
In `@src/Console/Commands/OpenApiCommand.php`:
- Line 201: In OpenApiCommand.php update the case of the OpenAPI directory check
so it matches the created/reference directory name: replace the string 'openApi'
with 'openapi' in the existence check (the code around the method in the
OpenApiCommand class that performs the directory existence validation), ensuring
consistency with other usages like the $fs->getJson call and the spec
installation logic that reference "openapi".

In
`@src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl`:
- Around line 69-108: The method parameter names in the OpenApi controller
template are inconsistent with the OpenAPI docs and routes: rename the parameter
$postId to $uuid in the abstract method signatures for post(), amend(),
delete(), and deleteImage() so the parameter name matches the `@OA`\Parameter
("uuid") and route definitions; update the signatures (e.g., abstract public
function post(?string $lang, string $postId) -> abstract public function
post(?string $lang, string $uuid)) for all four methods (post, amend, delete,
deleteImage) to keep names consistent across docs, routes and code.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1f09615b-d881-49ea-b967-6cbe8547478a

📥 Commits

Reviewing files that changed from the base of the PR and between 23d2ffc and b968a7f.

📒 Files selected for processing (5)

• src/Console/Commands/OpenApiCommand.php
• src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
• src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
• src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
• src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 90.87%. Comparing base (23d2ffc) to head (4e753bd).

Files with missing lines	Patch %	Lines
src/Console/Commands/OpenApiCommand.php	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #523   +/-   ##
=========================================
  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.