Added billable and project_id to time entry endpoints; Enhanced api docs; Added pagination

app/Extensions/Scramble/ApiExceptionTypeToSchema.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Extensions\Scramble;
+
+use App\Exceptions\Api\ApiException;
+use Dedoc\Scramble\Extensions\ExceptionToResponseExtension;
+use Dedoc\Scramble\Support\Generator\Reference;
+use Dedoc\Scramble\Support\Generator\Response;
+use Dedoc\Scramble\Support\Generator\Schema;
+use Dedoc\Scramble\Support\Generator\Types as OpenApiTypes;
+use Dedoc\Scramble\Support\Type\ObjectType;
+use Dedoc\Scramble\Support\Type\Type;
+use Illuminate\Support\Str;
+
+class ApiExceptionTypeToSchema extends ExceptionToResponseExtension
+{
+    public function shouldHandle(Type $type): bool
+    {
+        return $type instanceof ObjectType
+            && $type->isInstanceOf(ApiException::class);
+    }
+
+    public function toResponse(Type $type): Response
+    {
+        $validationResponseBodyType = (new OpenApiTypes\ObjectType())
+            ->addProperty(
+                'error',
+                (new OpenApiTypes\BooleanType())
+                    ->setDescription('Whether the response is an error.')
+            )
+            ->addProperty(
+                'key',
+                (new OpenApiTypes\StringType())
+                    ->setDescription('Error key.')
+            )
+            ->addProperty(
+                'message',
+                (new OpenApiTypes\StringType())
+                    ->setDescription('Error message.')
+            )
+            ->setRequired(['error', 'key', 'message']);
+
+        return Response::make(400)
+            ->description('API exception')
+            ->setContent(
+                'application/json',
+                Schema::fromType($validationResponseBodyType)
+            );
+    }
+
+    public function reference(ObjectType $type): Reference
+    {
+        return new Reference('responses', Str::start($type->name, '\\'), $this->components);
+    }
+}

app/Extensions/Scramble/PaginatedResourceCollectionTypeToSchema.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Extensions\Scramble;
+
+use App\Http\Resources\PaginatedResourceCollection;
+use Dedoc\Scramble\Extensions\TypeToSchemaExtension;
+use Dedoc\Scramble\Support\Generator\Response;
+use Dedoc\Scramble\Support\Generator\Schema;
+use Dedoc\Scramble\Support\Generator\Types\ArrayType;
+use Dedoc\Scramble\Support\Generator\Types\BooleanType;
+use Dedoc\Scramble\Support\Generator\Types\IntegerType;
+use Dedoc\Scramble\Support\Generator\Types\ObjectType as OpenApiObjectType;
+use Dedoc\Scramble\Support\Generator\Types\StringType;
+use Dedoc\Scramble\Support\Type\Generic;
+use Dedoc\Scramble\Support\Type\ObjectType;
+use Dedoc\Scramble\Support\Type\Type;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class PaginatedResourceCollectionTypeToSchema extends TypeToSchemaExtension
+{
+    public function shouldHandle(Type $type): bool
+    {
+        return $type instanceof ObjectType
+            && $type->isInstanceOf(PaginatedResourceCollection::class);
+    }
+
+    /**
+     * @param  Generic  $type
+     */
+    public function toResponse(Type $type): ?Response
+    {
+        /** @var Type|null $collectingClassType */
+        $collectingClassType = $type->templateTypes[0];
+
+        if (! $collectingClassType instanceof ObjectType) {
+            return null;
+        }
+
+        if (! $collectingClassType->isInstanceOf(JsonResource::class) && ! $collectingClassType->isInstanceOf(Model::class)) {
+            return null;
+        }
+
+        if (! ($collectingType = $this->openApiTransformer->transform($collectingClassType))) {
+            return null;
+        }
+
+        $type = new OpenApiObjectType;
+        $type->addProperty('data', (new ArrayType())->setItems($collectingType));
+        $type->addProperty(
+            'links',
+            (new OpenApiObjectType)
+                ->addProperty('first', (new StringType)->nullable(true))
+                ->addProperty('last', (new StringType)->nullable(true))
+                ->addProperty('prev', (new StringType)->nullable(true))
+                ->addProperty('next', (new StringType)->nullable(true))
+                ->setRequired(['first', 'last', 'prev', 'next'])
+        );
+        $type->addProperty(
+            'meta',
+            (new OpenApiObjectType)
+                ->addProperty('current_page', new IntegerType)
+                ->addProperty('from', (new IntegerType)->nullable(true))
+                ->addProperty('last_page', new IntegerType)
+                ->addProperty('links', (new ArrayType)->setItems(
+                    (new OpenApiObjectType)
+                        ->addProperty('url', (new StringType)->nullable(true))
+                        ->addProperty('label', new StringType)
+                        ->addProperty('active', new BooleanType)
+                        ->setRequired(['url', 'label', 'active'])
+                )->setDescription('Generated paginator links.'))
+                ->addProperty('path', (new StringType)->nullable(true)->setDescription('Base path for paginator generated URLs.'))
+                ->addProperty('per_page', (new IntegerType)->setDescription('Number of items shown per page.'))
+                ->addProperty('to', (new IntegerType)->nullable(true)->setDescription('Number of the last item in the slice.'))
+                ->addProperty('total', (new IntegerType)->setDescription('Total number of items being paginated.'))
+                ->setRequired(['current_page', 'from', 'last_page', 'links', 'path', 'per_page', 'to', 'total'])
+        );
+        $type->setRequired(['data', 'links', 'meta']);
+
+        return Response::make(200)
+            ->description('Paginated set of `'.$this->components->uniqueSchemaName($collectingClassType->name).'`')
+            ->setContent('application/json', Schema::fromType($type));
+    }
+}