feat: Routes can be marked as deprecated

[s-shiryaev]

In OpenAPI 3.0 it is possible to specify paths as deprecated. It is possible to implement this using custom spec generators, themes.

But I think it would be useful to implement native support.

Changes

1. Updated Metadata DTO
2. Updated Metadata strategies for DocBlock/Attributes
3. Updated base OpenApiSpecGenerator
4. Updated PostmanCollectionGenerator (Since Postman doesn't have a way to mark methods as deprecated, I decided to add the [DEPRECATED] suffix to method names.)
5. Updated default and elements themes
6. Updated tests

Usage

Just add a annotation @deprecated in method/class/route DocBlock:

/**
 * Update Role
 *
 * @deprecated
 */
public function update(string $id, CreateUpdateRoleRequest $request): Role
{
    $data = $request->validated();
    $model = $this->roleService->getModel($id, ['permissions']);

    return $this->roleService->updateRole($model, $data);
}

You can also use attributes:

#[Deprecated]
public function create(CreateUpdateRoleRequest $request): Role
{
    $data = $request->validated();

    return $this->roleService->createRole($data);
}

Examples

Default theme

Elements theme

External elements, scalar, rapidoc

[oralunal]

I was doing this by using HTML helpers. This is a good feature.

   /**
     * Daily Insights (Deprecated)
     *
     * <small class="badge badge-grey">Deprecated</small>
     *
     * Retrieve daily insights. <i>Deprecation Note: Use GET method instead.</i>
     */

It would be great if we can give more information about the deprecation.

[shalvah]

Wow, thank you for the thorough work.