README

概览

此组件使您能够标记API端点为弃用，并向客户端通知。

安装

通过composer安装包

composer require check24/apitk-deprecation-bundle

使用

弃用

您可以标记操作为弃用，以便开发者注意到他们必须更新API调用到较新版本或使用全新的端点。

use Shopping\ApiTKDeprecationBundle\Annotation\Deprecated;

/**
 * Returns the users in the system.
 *
 * @Rest\Get("/v2/users")
 * @Rest\View()
 *
 * @Deprecated(removedAfter="2018-10-09", since="2018-07-01", description="use /v3/users instead")
 
 * @param User[] $users
 * @return User[]
 */

在swagger文档内部显示通知，并将新的响应头x-apitk-deprecated: use /v3/users instead、x-apitk-deprecated-removed-at: 2018-10-09（如果设置了日期），x-apitk-deprecated-since: 2018-07-01（如果设置了日期）发送到客户端。

所有注解参数都是可选的，因此您可以只使用@Deprecated。在这种情况下，所有客户端都将收到一个x-apitk-deprecated: deprecated的响应头。该头的值可以通过提供上述示例中的description参数来覆盖。

如果您想从文档中隐藏特定的端点，请使用hideFromDocs=true参数在Deprecated注解中。相应的操作将不会显示。

类注解

从版本1.0.6开始，可以在Controller的类上放置@Deprecated注解，以标记所有包含的端点为弃用。
请注意，方法注解总是完全覆盖类注解。不会进行合并或其他操作。当一个控制器类有@Deprecated注解时，不可能标记控制器的一个或多个方法为非弃用。

弃用日志记录

从版本2.0.0开始，当调用弃用端点时，apitk-deprecation-bundle将抛出E_USER_DEPRECATED错误。当您使用NewRelic等APM工具，并希望在被调用弃用端点时收到通知时，这很有用。

弃用日志记录默认是激活的。您可以通过创建一个包含以下内容的config/packages/apitk_deprecation.yaml全局禁用它：

apitk_deprecation:
  trigger_deprecations: false # default: true

您还可以只为特定的端点激活/禁用弃用日志记录

/**
 * Always log deprecations for this route or class, ignoring global settings:
 * @Deprecated(description="use /v3/users instead", triggerDeprecation=true)
 * 
 * Never log deprecations for this route or class, ignoring global settings:
 * @Deprecated(description="use /v3/users instead", triggerDeprecation=false)
 * ...
 */