v3.3 | Make OpenAPI generation reusable and support @var array item types for views

[fenric]

What changed

This PR significantly reworks the OpenAPI part of sunrise/http-router.

The main goal of these changes is to make the OpenAPI API more reusable and less tightly coupled to HTTP Router itself. The OpenAPI generator is still shipped together with the router, but its internal architecture is now less dependent on a specific routing implementation and can be used as a standalone foundation for integrations with other frameworks.

One practical result of this refactoring is a separate Symfony bundle:

https://github.com/sunrise-studio-development/symfony-openapi

It uses the OpenAPI API from sunrise/http-router, while adding full support for Symfony routes and Symfony attributes. This is a good example of how the OpenAPI layer can now be extended and reused outside the main HTTP Router.

@var support for output/view objects

For users who use sunrise/http-router as their router, this PR also adds support for PHPDoc @var annotations when generating OpenAPI schemas for output/view objects.

Previously, describing array item types in OpenAPI required using the Subtype attribute from sunrise/hydrator. This was not always convenient, especially for response objects where Subtype was needed not for data hydration, but only to produce a correct OpenAPI schema.

Now array item types in view/output objects can be described with PHPDoc:

/**
 * @var UserView[]
 */
public array $users;

or with similar PHPDoc types supported by the parser.

Subtype is still relevant for input DTOs, where it is required for correct hydrator behavior. But response objects no longer need to use Subtype only for OpenAPI generation.

Why this matters

These changes make the OpenAPI part of the package more flexible:

• the OpenAPI API is now easier to use outside sunrise/http-router;
• integrations with other frameworks are easier to build;
• output/view objects no longer need an extra dependency on hydrator attributes just for documentation;
• users can describe array item types in the familiar PHPDoc way with @var.

Overall, the existing HTTP Router behavior remains compatible for current users, while the OpenAPI layer becomes more standalone and extensible.