search

nelmio / NelmioApiDocBundle

Generates documentation for your REST API from annotations
MIT License
2.23k stars 836 forks source link

NelmioApiDocBundle v5 overview #2215

Open DjordyKoert opened 9 months ago

DjordyKoert commented 9 months ago

I think we should start preparing for NelmioApiDocBundle v5 and move forward with this bundle.

PHP 8.1+

First of all I would like to remove support for PHP 7. PHP 7 has been EOL for quite some time now (PHP 7.4 active support stopped 2 years ago https://endoflife.date/php) and is currently preventing us from using new PHP 8 features (typed properties, native attributes, property promotion, union types).

Additionally I would like to start using PHP 8.1 as a minimum instead of PHP 8.0 because:

  1. Enums (could replace https://github.com/nelmio/NelmioApiDocBundle/blob/daadb0b567c637d737f58fd25da0b4db2321560d/Render/Html/AssetsMode.php)
  2. new in initializers https://stitcher.io/blog/new-in-php-81#new-in-initializers-rfc
  3. readonly properties

Planned changes:

Static analysis

PHP 8 is also a perfect time to start using static analysis tools. That's why I would like to introduce (PHPStan) to this project. This would also include some refactoring here and there to remove PHPStan's detected problems.

Symfony version bump to 6.4+ Drop support for Symfony 6.0, 6.1, 6.2 & 6.3

Symfony 6.0, 6.1, 6.2 & 6.3 have already stopped receiving bug fixes & security updates which is why a bump to Symfony 6.4 would be ideal, this version also closely align with our new minimum PHP version support. Additionaly let's keep supporting Symfony 5.4 for now. Support for it should be dropped in a different minor release. Preferably we wait until after November 2024 (end of bug fixes for Symfony 5.4 https://symfony.com/releases/5.4).

General refactoring

DjordyKoert commented 9 months ago

Try and and see if https://github.com/rectorphp/rector is a good solution for easy refactoring

mathroc commented 7 months ago

It could make upgrading harder, but it could be the opportunity to drop support for annotations. It seems to be that having both attributes & annotations adds a lot of complexity. Especially when the 2 are mixed

cjgordon commented 4 months ago

Just thought I would add this here.

As mentioned be @mathroc if a project switches to Attributes from Annotations (which I think makes sense) we would need to provide an upgrade path for going from annotations to attributes to bring most of the install base with us.

Fortunately rectorphp gets us there... nearly. See: https://github.com/zircote/swagger-php/issues/1047

I have used this method with only one issue I had to manually fix which is this issue with nested annotations: https://github.com/zircote/swagger-php/issues/1047#issuecomment-1950430218

Will see what I can do to resolve this as I would like to migrate my own project.

DjordyKoert commented 3 months ago

I'm gonna go ahead and close this issue. After some careful thinking and researching I have decided that an upgrade to either Symfony or PHP do not fall under a breaking change to our exposed bundle API and thus shouldn't need to only happen inside of a major update.

See this post by doctrine https://www.doctrine-project.org/2017/07/25/php-7.1-requirement-and-composer.html

Releasing v5 for the current deprecations inside the bundle aren't worth it currently as I am still not happy with certain implementations.

DjordyKoert commented 1 month ago

Reopening this issue because I encountered various issues in the codebase while attempting to bump Symfony minimum to 6.4 in https://github.com/nelmio/NelmioApiDocBundle/pull/2335.

Most of these issues were related to updating the tests to prefer attributes over annotations.

In the end I strongly believe that in order for this bundle to be ready for the future we will have to move to a major v5 by doing the changes mentioned in this issue.