README

一套用于Laravel项目的API工具。

安装

先决条件

PHP7.1+
Laravel项目

通过composer在Laravel项目中安装

运行composer命令

composer require mpokket/laravel-api-helper

注册服务提供者

在config/app.php中，将服务提供者添加到$providers数组中

'providers' => [
    ...
    Mpokket\APIHelper\APIHelperServiceProvider::class,
    ...
]

APIHelperServiceProvider

APIHelperServiceProvider为您的API方法提供Mpokket\APIHelper\Annotations\Deprecation注解，支持以下IETF RFCs：

RFC8594 - 夕阳HTTP头部字段
网络草案 draft-dalal-deprecation-header-01 - 弃用HTTP头部字段

用法

要为您的API添加夕阳和弃用，请在API方法上直接使用以下注解。

注解选项

/**
* @Deprecation(since=true) // If you don't know the date the API will deprecated on
* Deprecation annotation attributes
* since - true or the date and time (optional)
* sunset - Date and time (optional)
* alternate - URL for superseding API
* policy - URL for sunset policy 
*/

示例响应头

示例 1

注解

use Mpokket\APIHelper\Annotations\Deprecation; // DO NOT FORGET TO IMPORT THE ANNOTATION

/**
* Display a listing of the resource.
*
* @Deprecation(since="true") // or
* @Deprecation(since=true) // or
* @Deprecation(since="01-01-2023")
*
* @return \Illuminate\Http\Response
*/
public function index()
{
    return response('...');
}

Deprecation: true

示例 2

注解

use Mpokket\APIHelper\Annotations\Deprecation; // DO NOT FORGET TO IMPORT THE ANNOTATION

/**
* Display a listing of the resource.
*
* @Deprecation(since="31-12-2022", alternate=" https://domain.com/your/next/version/api", 
*     policy="https://domain.com/api/deprecation/policy", sunset="01-01-2022")
*
* @return \Illuminate\Http\Response
*/
public function index()
{
    return response('...');
}

响应头

Sunset: Mon, 01 Jan 2022 00:00:00 GMT
Deprecation: Mon, 31 Dec 2022 00:00:00 GMT
Link: https://domain.com/your/next/version/api; rel=alternate, https://domain.com/api/deprecation/policy; rel=deprecation

注意

弃用头IETF提案目前处于草案状态
未为测试弃用中间件编写PHPUnit测试

调试

在非生产环境中，如果有任何来自中间件的异常，将会有一个指向异常和行号的响应头。在报告问题时，请与控制器方法注解一起使用此功能。

支持

如果您需要任何支持，请使用该项目的问题跟踪器GitHub。

贡献

欢迎拉取请求。对于主要更改，请先提出问题以讨论您想要更改的内容。

请确保根据需要更新测试。

许可证

MIT

mpokket / laravel-api-helper

维护者

详细信息