Merge pull request #2 from Rocksheep/feature/allow-developers-to-add-…

…descriptions-to-endpoints

Feature/allow developers to add descriptions to endpoints

.gitignore

@@ -1,3 +1,4 @@
 /vendor
 composer.lock
-.phpunit.result.cache
+.phpunit.result.cache
+.idea

composer.json

@@ -22,7 +22,7 @@
         "symfony/yaml": "^5.3"
     },
     "require-dev": {
-        "laravel-json-api/laravel": "^1.0",
+        "laravel-json-api/laravel": "^2.0",
         "orchestra/testbench": "^6.9",
         "phpunit/phpunit": "^9.5",
         "ext-json": "*"

src/Contracts/DescribesEndpoints.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace LaravelJsonApi\OpenApiSpec\Contracts;
+
+interface DescribesEndpoints
+{
+    public function describeEndpoint(string $endpoint): string;
+}

src/Descriptors/Actions/ActionDescriptor.php

@@ -11,6 +11,7 @@
 use LaravelJsonApi\OpenApiSpec\Builders\Paths\Operation\ParameterBuilder;
 use LaravelJsonApi\OpenApiSpec\Builders\Paths\Operation\RequestBodyBuilder;
 use LaravelJsonApi\OpenApiSpec\Builders\Paths\Operation\ResponseBuilder;
+use LaravelJsonApi\OpenApiSpec\Contracts\DescribesEndpoints;
 use LaravelJsonApi\OpenApiSpec\Contracts\Descriptors\ActionDescriptor as ActionDescriptorContract;
 use LaravelJsonApi\OpenApiSpec\Generator;
 use LaravelJsonApi\OpenApiSpec\Route;
@@ -80,7 +81,14 @@ public function action(): Operation
      */
     protected function description(): string
     {
-        return '';
+        /** @var DescribesEndpoints $schema */
+        $schema = $this->route->schema();
+
+        if (!$schema instanceof DescribesEndpoints) {
+            return '';
+        }
+
+        return $schema->describeEndpoint($this->route->route()->getName());
     }
 
     /**

src/Descriptors/Schema/Schema.php

@@ -111,7 +111,7 @@ public function store(Route $route): OASchema
             OASchema::object('attributes')
               ->properties(...$fields->get('attributes')),
             OASchema::object('relationships')
-              ->properties(...$fields->get('relationships'))
+              ->properties(...$fields->get('relationships') ?: [])
           );
     }
 
@@ -140,7 +140,7 @@ public function update(Route $route): OASchema
             OASchema::object('attributes')
               ->properties(...$fields->get('attributes')),
             OASchema::object('relationships')
-              ->properties(...$fields->get('relationships'))
+              ->properties(...$fields->get('relationships') ?: [])
           )
           ->required('type', 'id', 'attributes');
     }

src/Generator.php

@@ -6,6 +6,7 @@
 
 use GoldSpecDigital\ObjectOrientedOAS\OpenApi;
 use LaravelJsonApi\Contracts\Server\Server;
+use LaravelJsonApi\Core\Support\AppResolver;
 use LaravelJsonApi\OpenApiSpec\Builders\InfoBuilder;
 use LaravelJsonApi\OpenApiSpec\Builders\PathsBuilder;
 use LaravelJsonApi\OpenApiSpec\Builders\ServerBuilder;
@@ -37,10 +38,9 @@ public function __construct($key)
         $this->key = $key;
 
         $apiServer = config("jsonapi.servers.$key");
-        $app = app();
+        $appResolver = app(AppResolver::class);
 
-
-        $this->server = new $apiServer($app, $this->key);
+        $this->server = new $apiServer($appResolver, $this->key);
 
         $this->infoBuilder = new InfoBuilder($this);
         $this->serverBuilder = new ServerBuilder($this);

tests/Feature/OpenApiSchemaTest.php

@@ -29,4 +29,16 @@ public function test_has_many_should_have_array_as_type(): void
         $this->assertEquals('array', $this->spec['components']['schemas']['resources.posts.relationship.tags.attach']['type']);
         $this->assertEquals('array', $this->spec['components']['schemas']['resources.posts.relationship.tags.detach']['type']);
     }
+
+    public function test_it_uses_the_description_from_the_schema()
+    {
+        $this->assertEquals('This is an example show all description', $this->spec['paths']['/posts']['get']['description']);
+        $this->assertEquals('This is an example show one description', $this->spec['paths']['/posts/{post}']['get']['description']);
+        $this->assertEquals('This is an example show posts author description', $this->spec['paths']['/posts/{post}/author']['get']['description']);
+    }
+
+    public function test_it_creates_an_empty_description_if_a_schema_does_not_implement_the_describes_actions_interface()
+    {
+        $this->assertEquals('', $this->spec['paths']['/videos']['get']['description']);
+    }
 }

tests/Support/JsonApi/V1/Posts/PostSchema.php

@@ -20,6 +20,7 @@
 namespace LaravelJsonApi\OpenApiSpec\Tests\Support\JsonApi\V1\Posts;
 
 use LaravelJsonApi\HashIds\HashId;
+use LaravelJsonApi\OpenApiSpec\Contracts\DescribesEndpoints;
 use LaravelJsonApi\OpenApiSpec\Tests\Support\Models\Post;
 use LaravelJsonApi\Eloquent\Fields\DateTime;
 use LaravelJsonApi\Eloquent\Fields\Relations\BelongsTo;
@@ -37,7 +38,7 @@
 use LaravelJsonApi\Eloquent\SoftDeletes;
 use LaravelJsonApi\Eloquent\Sorting\SortCountable;
 
-class PostSchema extends Schema
+class PostSchema extends Schema implements DescribesEndpoints
 {
 
     use SoftDeletes;
@@ -61,6 +62,17 @@ class PostSchema extends Schema
      */
     protected $defaultSort = '-createdAt';
 
+    private array $descriptions = [
+        'v1.posts.index' => 'This is an example show all description',
+        'v1.posts.show' => 'This is an example show one description',
+        'v1.posts.author' => 'This is an example show posts author description',
+    ];
+
+    public function describeEndpoint(string $endpoint): string
+    {
+        return $this->descriptions[$endpoint] ?? '';
+    }
+
     /**
      * @inheritDoc
      */