[armanist]

Closes #597. Part of #595. The changelog entry is written in a final pull request, after the sub-issues.

What changed

• The seven annotated API module templates (DefaultApi: OpenApiController, OpenApiMainController; DemoApi: OpenApiController and the Comment, Account, Post and Auth controllers) describe the API with #[OA\...] attributes instead of @OA\... docblocks. Values are unchanged; text lines of the docblocks are kept.
• The documentation version in the two OpenApiController templates is 3.x instead of 2.9.0.
• doctrine/annotations is removed from composer.json. Nothing in src used it.
• OpenApiTemplatesTest renders the API templates and runs swagger-php on them: the specification must validate, describe the API and its security scheme, give every operation a summary and responses, and no template may contain @OA\ again.

Why

swagger-php 5 reads attributes natively and needs doctrine/annotations only for docblock annotations, where it is just a suggestion. The package is abandoned, so the framework should not require it. New modules start with attributes.

Breaking changes

• doctrine/annotations is no longer installed with the framework. An existing application whose controllers use @OA docblocks must convert them to #[OA\...] attributes, or require doctrine/annotations itself. Otherwise install:openapi fails with Required @OA\PathItem() not found.
• Modules generated from the templates before this change are not affected until they are regenerated.

Testing

• OpenApiTemplatesTest is new (8 tests).
• Before and after, the specification generated from each template set is identical: DefaultApi (1 path) and DemoApi (20 paths, 20 operations) compared as normalized JSON, apart from the 3.x version.
• A module generated with module:generate -t DemoApi and published with install:openapi shows its 20 paths in Swagger UI in the browser. The DefaultApi module generates a valid specification with 1 path.
• Known gap: the test does not notice an operation losing one of several responses. The before and after comparison covered that and is not part of the suite.

Notes for reviewers

• install:openapi fails when the module has no resources folder (mkdir() is not recursive) and when public/assets/OpenApiUi does not exist. Both exist before this change and are not touched here.

Summary by CodeRabbit

• Documentation

  • Generated API templates now describe OpenAPI metadata using PHP attributes. Existing endpoint details, security settings, request fields, and response information are retained.
  • The documented API version is now 3.x.

• Chores

  • Removed the doctrine/annotations dependency.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: a559ceff-d209-473f-8188-600675a7fdcd

📥 Commits

Reviewing files that changed from the base of the PR and between 84fb2ae and e8ddf56.

📒 Files selected for processing: 9

• composer.json
• src/Module/Templates/DefaultApi/src/Controllers/OpenApi/OpenApiController.php.tpl
• src/Module/Templates/DefaultApi/src/Controllers/OpenApi/OpenApiMainController.php.tpl
• 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/OpenApiController.php.tpl
• src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
• tests/Unit/Module/Templates/OpenApiTemplatesTest.php

💤 Files with no reviewable changes: 1

• composer.json

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The API templates replace OpenAPI docblock annotations with PHP attributes. The change removes doctrine/annotations from the required dependencies and adds tests that generate and validate specifications from the DefaultApi and DemoApi templates.

Changes: OpenAPI template conversion

Layer / File(s)	Summary
Default API attributes composer.json, src/Module/Templates/DefaultApi/src/Controllers/OpenApi/*	The DefaultApi metadata and main endpoint use PHP attributes instead of docblock annotations. The documented API version changes from 2.9.0 to 3.x. doctrine/annotations is removed from require.
Demo API authentication and account endpoints src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiController.php.tpl, src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl, src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl	The API metadata, account operations, and authentication operations use PHP attributes. Their documented paths, parameters, request details, security requirements, responses, and examples are retained.
Demo API content endpoints and validation src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl, src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl, tests/Unit/Module/Templates/OpenApiTemplatesTest.php	The comment and post operations use PHP attributes. Tests render both templates and check the generated specifications, operation summaries and responses, security scheme, and absence of @OA\ annotations.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Refactor

Suggested reviewers: andrey-smaelov

Merge Risk: ⚪ Minimal · up to e8ddf

The API templates now describe their OpenAPI documentation with PHP attributes, which the supported PHP 8.1+ runtime handles. API documentation generation no longer needs doctrine/annotations. Existing projects that still use @OA docblocks must convert them to attributes or require doctrine/annotations themselves. That migration guidance is still to be documented, but no blocking code risk remains.

Pre-merge checks: 3 · 2

Failed checks: 2 warnings

Check name	Status	Explanation	Resolution
Linked Issues check		The changes satisfy the main implementation objectives in #597: the seven API templates use #[OA\\...] attributes, doctrine/annotations is removed, and OpenApiTemplatesTest validates generated sp…	Keep the generated API documentation content unchanged, including Info.version, unless #597 is updated. Add the required changelog and upgrade-guide migration note. The note must explain conversion from @OA\\... docblocks or requiring `d…
Out of Scope Changes check		The template conversion, dependency removal, and validation test are within #597. The Info.version value changes from 2.9.0 to 3.x in both OpenApiController templates. #597 explicitly excludes…	Remove the Info.version changes, or update the linked issue to include this documentation-content change.

Passed checks: 3 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title "Issue/597 Write the OpenAPI docs in the API templates as attributes" matches the main change. The PR converts the OpenAPI docblock annotations (@OA\...) in the DefaultApi and DemoApi templa…
Docstring Coverage		Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 1 files. (7 skipped: 7 u…

Full details: Title check

Explanation

The title "Issue/597 Write the OpenAPI docs in the API templates as attributes" matches the main change. The PR converts the OpenAPI docblock annotations (@OA...) in the DefaultApi and DemoApi templates to PHP attributes (#[OA...]). The title names the issue number, which adds noise but does not make it misleading. It is 67 characters and 11 words, so it is a bit long but still a single, specific sentence.

Full details: Docstring Coverage

Explanation

Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 1 files. (7 skipped: 7 unsupported.)

Full details: Linked Issues check

Explanation

The changes satisfy the main implementation objectives in #597: the seven API templates use #[OA\...] attributes, doctrine/annotations is removed, and OpenApiTemplatesTest validates generated specifications. The PR changes the generated OpenAPI Info.version from 2.9.0 to 3.x, so the specification is not identical as required. The PR also adds no changelog or upgrade-guide note. The required upgrade note must explain conversion of existing @OA\... annotations. The diff contains no CHANGELOG.md change, and the PR states that the changelog is deferred.

Resolution

Keep the generated API documentation content unchanged, including Info.version, unless #597 is updated. Add the required changelog and upgrade-guide migration note. The note must explain conversion from @OA\... docblocks or requiring doctrine/annotations. Run and verify composer test, composer cs:check, composer phpstan, and composer rector:check.

Full details: Out of Scope Changes check

Explanation

The template conversion, dependency removal, and validation test are within #597. The Info.version value changes from 2.9.0 to 3.x in both OpenApiController templates. #597 explicitly excludes changes to API documentation content, and this value is API documentation content.

Resolution

Remove the Info.version changes, or update the linked issue to include this documentation-content change.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!