README

Laravel API Docs [测试版]

该包仍在测试版，尚未准备好用于生产环境

根据您的应用路由和便捷的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）。请查阅许可协议文件以获取更多信息。