README

令人惊叹的 scribe 包可以从您的 Laravel 项目自动生成 API 文档。

此包添加了 PHP 8 注解，因此您可以在您喜欢的 IDE 中使用自动完成功能。它还可以自动从您的 JsonResource 中的 mixin 注解确定相关的模型名称。

注解

匿名资源集合

<?php

use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Magwel\ScribeAnnotations\Attributes\ApiResource;
 
class UserController
{
    #[ApiResource(User::class, UserResource::class)]
    public function __invoke(): AnonymousResourceCollection
    {
        $users = User::all();
        
        return UserResource::collection($users);
    }
}

自定义状态码

<?php

use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Magwel\ScribeAnnotations\Attributes\ApiResource;
 
class UserController
{
    #[ApiResource(User::class, UserResource::class, statusCode: 201)]
    public function __invoke(): AnonymousResourceCollection
    {
        $users = User::all();
        
        return UserResource::collection($users);
    }
}

工厂状态

<?php

class TestUserFactory extends Factory
{
    protected $model = TestUser::class;

    public function randomState(): self
    {
        return $this->state(function () {
            return [
                'randomState' => true,
            ];
        });
    }

    public function definition(): array
    {
        return [
            'first_name' => 'Tested',
            'last_name' => 'Again',
            'email' => 'a@b.com',
        ];
    }
}

<?php

use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Magwel\ScribeAnnotations\Attributes\ApiResource;
 
class UserController
{
    #[ApiResource(User::class, UserResource::class, factoryStates: ['randomState'])]
    public function __invoke(): AnonymousResourceCollection
    {
        $users = User::all();
        
        return UserResource::collection($users);
    }
}

自动确定资源模型来自资源 mixin

/**
 * @mixin App\Models\User;
 */
class UserResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->first_name . ' ' . $this->last_name,
        ];
    }
}

<?php

use App\Models\User;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
use Magwel\ScribeAnnotations\Attributes\ApiResource;
 
class UserController
{
    public function __invoke(): UserResource
    {
        $users = User::first();
        
        return new UserResource($users);
    }
}