README

Laravel API Docs [Beta]

该软件包仍处于测试版，尚未准备好用于生产使用

根据您的应用程序路由和PHP 8属性自动生成laravel API的文档

安装

首先，使用composer按以下要求引入软件包

composer require ukfast/laravel-api-docs

然后，我们只需要在config/app.php的providers键中注册服务提供者

UKFast\LaravelApiDocs\ServiceProvider::class,

使用方法

通过扫描路由文件并查找带有特殊端点属性标记的控制器方法来生成文档

虽然您可以轻松地定义自己的端点类型，但该软件包提供了一些合理的默认值，通常符合laravel默认值

索引

索引端点用于返回分页列表的端点，例如

use UKFast\LaravelApiDocs\Endpoints;
use App\Http\Resources\PetResource;
use App\Models\Pet;

class PetController
{
    #[Endpoints\Index(PetResource::class)]
    public function index()
    {
        return PetResource::collection(Pet::paginate());
    }
}

创建

创建端点用于创建新资源

use UKFast\LaravelApiDocs\Endpoints;
use App\Http\Resources\PetResource;
use App\Models\Pet;

class PetController
{
    #[Endpoints\Create(PetResource::class)
    public function store()
    {
    }
}

显示

显示端点显示单个资源

use UKFast\LaravelApiDocs\Endpoints;
use App\Http\Resources\PetResource;
use App\Models\Pet;

class PetController
{
    #[Endpoints\Show(PetResource::class)
    public function show()
    {
    }
}

更新

更新端点更新资源

use UKFast\LaravelApiDocs\Endpoints;
use App\Http\Resources\PetResource;
use App\Models\Pet;

class PetController
{
    #[Endpoints\Update(PetResource::class)
    public function update()
    {
    }
}

销毁

销毁端点删除资源

use UKFast\LaravelApiDocs\Endpoints;

class PetController
{
    #[Endpoints\Destroy]
    public function destroy()
    {
    }
}

自定义请求和响应结构

您的API可能有自己的格式，与该软件包提供的默认格式不同。但重新定义这些并不困难。

以下是一个自定义索引端点的示例

namespace App\Docs;

use UKFast\LaravelApiDocs\Endpoint;
use Attribute;

#[Attribute]
class Index extends Endpoint
{
    public function __construct(protected $resource)
    {}

    public function response()
    {
        return [
            'data' => [$this->ref($this->resource)],
            'meta' => [
                'per_page' => 15,
                'total_pages' => 10,
                'current_page' => 1,
            ],
        ];
    }
}

端点类可以定义两个方法：`request`和`response`，每个方法返回一个PHP数组，概述请求结构。

调用`$this->ref`时，可以传递一个带有#[Resource]属性的任何类的类路径。

更多示例请参阅src/Endpoints文件夹

贡献

我们欢迎社区对此软件包的贡献。

您可以通过open-source@ukfast.co.uk联系我们的开源团队，他们会尽快回复您。

有关更多信息，请参阅我们的CONTRIBUTING文件。

安全

如果您认为已识别到安全漏洞，请通过security@ukfast.co.uk联系我们的团队，他们会尽快回复您，而不是使用问题跟踪器。

许可证

此项目采用MIT许可证（MIT）。有关更多信息，请参阅许可证文件。