Open API generator changes

.gitignore

@@ -6,3 +6,4 @@ node_modules
 .phpunit.result.cache
 docs/.vitepress/dist
 docs/.vitepress/cache
+.idea/*

src/Endpoint/CollectionAction.php

@@ -6,17 +6,21 @@
 use Nyholm\Psr7\Response;
 use Psr\Http\Message\ResponseInterface;
 use Tobyz\JsonApiServer\Context;
+use Tobyz\JsonApiServer\Endpoint\Concerns\BuildsOpenApiPaths;
 use Tobyz\JsonApiServer\Exception\ForbiddenException;
 use Tobyz\JsonApiServer\Exception\MethodNotAllowedException;
 use Tobyz\JsonApiServer\OpenApi\OpenApiPathsProvider;
 use Tobyz\JsonApiServer\Resource\Collection;
 use Tobyz\JsonApiServer\Schema\Concerns\HasDescription;
+use Tobyz\JsonApiServer\Schema\Concerns\HasSummary;
 use Tobyz\JsonApiServer\Schema\Concerns\HasVisibility;
 
 class CollectionAction implements Endpoint, OpenApiPathsProvider
 {
     use HasVisibility;
+    use HasSummary;
     use HasDescription;
+    use BuildsOpenApiPaths;
 
     public string $method = 'POST';
 
@@ -52,20 +56,25 @@ public function handle(Context $context): ?ResponseInterface
             throw new ForbiddenException();
         }
 
-        ($this->handler)($context);
-
-        return new Response(204);
+        return ($this->handler)($context) ?? new Response(204);
     }
 
     public function getOpenApiPaths(Collection $collection): array
     {
         return [
             "/{$collection->name()}/$this->name" => [
                 'post' => [
+                    'summary' => $this->getSummary(),
                     'description' => $this->getDescription(),
                     'tags' => [$collection->name()],
                     'responses' => [
-                        '204' => [],
+                        '204' => [
+                            'description' => 'No Content',
+                        ],
+                        '400' => $this->buildBadRequestErrorResponse(),
+                        '401' => $this->buildUnauthorizedErrorResponse(),
+                        '403' => $this->buildForbiddenErrorResponse(),
+                        '500' => $this->buildInternalServerErrorResponse(),
                     ],
                 ],
             ],

src/Endpoint/Concerns/BuildsOpenApiPaths.php

@@ -2,21 +2,299 @@
 
 namespace Tobyz\JsonApiServer\Endpoint\Concerns;
 
+use ReflectionException;
+use ReflectionFunction;
+use Tobyz\JsonApiServer\Endpoint\Index;
 use Tobyz\JsonApiServer\JsonApi;
+use Tobyz\JsonApiServer\Resource\Collection;
+use Tobyz\JsonApiServer\Resource\Resource;
+use Tobyz\JsonApiServer\Schema\Field\Field;
+use Tobyz\JsonApiServer\Schema\Field\Relationship;
+use Tobyz\JsonApiServer\Schema\Filter;
 
 trait BuildsOpenApiPaths
 {
-    private function buildOpenApiContent(array $resources, bool $multiple = false): array
-    {
+    private function buildOpenApiContent(
+        string $name,
+        array $resources,
+        bool $multiple = false,
+        bool $included = true,
+        bool $links = false,
+        bool $countable = false,
+        bool $paginatable = false,
+    ): array {
         $item = count($resources) === 1 ? $resources[0] : ['oneOf' => $resources];
 
         return [
             JsonApi::MEDIA_TYPE => [
                 'schema' => [
                     'type' => 'object',
                     'required' => ['data'],
-                    'properties' => [
+                    'properties' => array_filter([
+                        'links' => $links ? $this->buildLinksObject($name) : [],
                         'data' => $multiple ? ['type' => 'array', 'items' => $item] : $item,
+                        'included' => $included ? ['type' => 'array'] : [],
+                        'meta' => $this->buildMetaObject($countable, $paginatable),
+                    ]),
+                ],
+            ],
+        ];
+    }
+
+    private function buildLinksObject(string $name): array
+    {
+        // @todo: maybe pull in the API or Context to return a server name?
+        $baseUri = sprintf('https://{server}/%s', $name);
+        $defaultQuery = ['page[limit]' => 10];
+
+        $links = [
+            'self' => ['page[offset]' => 2],
+            'first' => ['page[offset]' => 1],
+            'prev' => ['page[offset]' => 1],
+            'next' => ['page[offset]' => 3],
+            'last' => ['page[offset]' => 10],
+        ];
+
+        foreach ($links as $key => $params) {
+            $params = $params + $defaultQuery;
+
+            $query = implode(
+                '&',
+                array_map(
+                    fn($k, $v) => $k . '=' . urlencode($v),
+                    array_keys($params),
+                    $params,
+                )
+            );
+
+            $links[$key] = sprintf('%s/%s', $baseUri, $query);
+        }
+
+        return [
+            'type' => 'object',
+            'properties' => array_map(function (string $uri) {
+                return [
+                    'type' => 'string',
+                    'example' => $uri,
+                ];
+            }, $links),
+        ];
+    }
+
+    private function buildMetaObject(bool $countable, bool $paginatable): array
+    {
+        if (!($countable || $paginatable)) {
+            return [];
+        }
+
+        return [
+            'type' => 'object',
+            'properties' => [
+                'page' => [
+                    'type' => 'object',
+                    'properties' => array_filter([
+                        'total' => $countable ? ['type' => 'integer'] : [],
+                        'limit' => $paginatable ? ['type' => 'integer'] : [],
+                        'offset' => $paginatable ? ['type' => 'integer'] : [],
+                    ]),
+                ],
+            ],
+        ];
+    }
+
+    /**
+     * @throws ReflectionException
+     */
+    private function buildOpenApiParameters(Collection $collection): array
+    {
+        // @todo: fix this
+        assert($collection instanceof Resource);
+
+        $parameters = [
+            $this->buildIncludeParameter($collection),
+            ...$this->buildFilterParameters($collection),
+            ...$this->buildPaginatableParameters(),
+        ];
+
+        return array_values(array_filter($parameters));
+    }
+
+    private function buildIncludeParameter(Resource $resource): array
+    {
+        $relationshipNames = array_map(
+            fn(Relationship $relationship) => $relationship->name,
+            array_filter(
+                $resource->fields(),
+                fn(Field $field) => $field instanceof Relationship && $field->includable,
+            ),
+        );
+
+        if (empty($relationshipNames)) {
+            return [];
+        }
+
+        $includes = implode(', ', $relationshipNames);
+
+        return [
+            'name' => 'include',
+            'in' => 'query',
+            'description' => "Available include parameters: {$includes}.",
+            'schema' => [
+                'type' => 'string',
+            ],
+        ];
+    }
+
+
+    private function buildFilterParameters(Resource $resource): array
+    {
+        if (!$this instanceof Index) {
+            return [];
+        }
+
+        return array_map(function (Filter $filter) {
+            return [
+                'name' => "filter[{$filter->name}]",
+                'in' => 'query',
+                'description' => $filter->getDescription(),
+                'schema' => [
+                    'type' => 'string',
+                ],
+            ];
+        }, $resource->filters());
+    }
+
+    /**
+     * @throws ReflectionException
+     */
+    private function buildPaginatableParameters(): array
+    {
+        if (property_exists($this, 'paginationResolver')) {
+            $resolver = $this->paginationResolver;
+            $reflection = new ReflectionFunction($resolver);
+
+            if ($reflection->getNumberOfRequiredParameters() > 0) {
+                return [
+                    [
+                        'name' => 'page[limit]',
+                        'in' => 'query',
+                        'description' => "The limit pagination field.",
+                        'schema' => [
+                            'type' => 'number',
+                        ],
+                    ],
+                    [
+                        'name' => 'page[offset]',
+                        'in' => 'query',
+                        'description' => "The offset pagination field.",
+                        'schema' => [
+                            'type' => 'number',
+                        ],
+                    ],
+                ];
+            }
+        }
+
+        return [];
+    }
+
+    public function buildBadRequestErrorResponse(): array
+    {
+        return $this->buildErrorResponse(
+            'A bad request.',
+            400,
+            'Bad Request',
+            'Please try again with a valid request.',
+        );
+    }
+
+    public function buildUnauthorizedErrorResponse(): array
+    {
+        return $this->buildErrorResponse(
+            'An unauthorised error.',
+            401,
+            'Unauthorized',
+            'Please login and try again.',
+        );
+    }
+
+    public function buildForbiddenErrorResponse(): array
+    {
+        return $this->buildErrorResponse(
+            'A forbidden error.',
+            403,
+            'Forbidden',
+        );
+    }
+
+    public function buildNotFoundErrorResponse(): array
+    {
+        return $this->buildErrorResponse(
+            'A bad request.',
+            404,
+            'Not Found',
+            'The requested resource could not be found.',
+        );
+    }
+
+    public function buildInternalServerErrorResponse(): array
+    {
+        return $this->buildErrorResponse(
+            'A bad request.',
+            500,
+            'Internal Server Error',
+            'Please try again later.',
+        );
+    }
+
+    public function buildErrorResponse(string $description, int $status, string $title, ?string $detail = null): array
+    {
+        return [
+            'description' => $description,
+            'content' => [
+                JsonApi::MEDIA_TYPE => [
+                    'schema' => [
+                        'type' => 'object',
+                        'properties' => [
+                            'errors' => [
+                                'type' => 'array',
+                                'items' => [
+                                    'type' => 'object',
+                                    'required' => [
+                                        'status',
+                                        'title',
+                                    ],
+                                    'properties' => array_filter([
+                                        'status' => [
+                                            'type' => 'string',
+                                            'example' => (string)$status,
+                                        ],
+                                        'title' => [
+                                            'type' => 'string',
+                                            'example' => $title,
+                                        ],
+                                        'detail' => [
+                                            'type' => 'string',
+                                            'example' => $detail,
+                                        ],
+                                        'source' => [
+                                            'type' => 'object',
+                                            'properties' => [
+                                                'pointer' => [
+                                                    'type' => 'string',
+                                                ],
+                                                'parameter' => [
+                                                    'type' => 'string',
+                                                ],
+                                                'header' => [
+                                                    'type' => 'string',
+                                                ],
+                                            ],
+                                        ],
+                                    ]),
+                                ],
+                            ],
+                        ],
                     ],
                 ],
             ],

src/Endpoint/Concerns/SavesData.php

@@ -176,7 +176,7 @@ private function assertDataValid(Context $context, array $data, bool $validateAl
         foreach ($context->fields($context->resource) as $field) {
             $empty = !has_value($data, $field);
 
-            if ($empty && (!$field->required || !$validateAll)) {
+            if ($empty && (!$field->isRequired($context) || !$validateAll)) {
                 continue;
             }
 
@@ -187,7 +187,7 @@ private function assertDataValid(Context $context, array $data, bool $validateAl
                 ];
             };
 
-            if ($empty && $field->required) {
+            if ($empty && $field->isRequired($context)) {
                 $fail('field is required');
             } else {
                 $field->validateValue(get_value($data, $field), $fail, $context->withField($field));