bertvanhoekelen/scribe-annotations

Ability to add documentation based on PHP annotations

0.3.0 2022-09-01 09:53 UTC

Requires

• php: 8.0.*|8.1.*
• illuminate/console: ^6.0|^7.0|^8.0|^9.0
• illuminate/routing: ^6.0|^7.0|^8.0|^9.0
• illuminate/support: ^6.0|^7.0|^8.0|^9.0
• knuckleswtf/scribe: ^3.31

Requires (Dev)

• dms/phpunit-arraysubset-asserts: ^0.4.0
• friendsofphp/php-cs-fixer: ^3.8
• laravel/framework: ^9.17
• nunomaduro/larastan: ^2.1
• orchestra/testbench: ^4.0|^5.0|^6.0|^7.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.1

MIT

• Bert van Hoekelen

README

The amazing scribe package can generate API documentation automatically from your Laravel project.

This package adds PHP 8 annotations, so you can make use of autocompletion in your favorite IDE. It can also automatically determine related model names from the mixin annotation in your JsonResource.

Annotation's

Anonymous resource collections

<?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);
    }
}

Custom status code

<?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);
    }
}

Factory states

<?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' => '[e-mail]',
        ];
    }
}

<?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);
    }
}

Automatically determine resource model from resource 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);
    }
}