Retrieve description from schema if available

swisnl · Feb 21, 2022 · 507a8d3 · 507a8d3
1 parent 193ede7
commit 507a8d3
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 2 deletions.
diff --git a/src/Contracts/DescribesEndpoints.php b/src/Contracts/DescribesEndpoints.php
@@ -0,0 +1,8 @@
+<?php
+
+namespace LaravelJsonApi\OpenApiSpec\Contracts;
+
+interface DescribesEndpoints
+{
+    public function describeEndpoint(string $endpoint): string;
+}
diff --git a/src/Descriptors/Actions/ActionDescriptor.php b/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());
     }
 
     /**

diff --git a/tests/Feature/OpenApiSchemaTest.php b/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']);
+    }
 }
diff --git a/tests/Support/JsonApi/V1/Posts/PostSchema.php b/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
      */