Implemented simpler resource attributes descriptions (#463)

* added comments description * removed unused import
dedoc · Jul 19, 2024 · 60596e9 · 60596e9
1 parent 5b3afc1
commit 60596e9
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 2 deletions.
diff --git a/src/Support/Generator/TypeTransformer.php b/src/Support/Generator/TypeTransformer.php
@@ -121,8 +121,10 @@ public function transform(Type $type)
                     ? $this->transform(PhpDocTypeHelper::toType($varNode->type))
                     : $openApiType;
 
-                if ($varNode && $varNode->description) {
-                    $openApiType->setDescription($varNode->description);
+                $commentDescription = trim($docNode->getAttribute('summary').' '.$docNode->getAttribute('description'));
+                $varNodeDescription = $varNode && $varNode->description ? trim($varNode->description) : '';
+                if ($commentDescription || $varNodeDescription) {
+                    $openApiType->setDescription(implode('. ', array_filter([$varNodeDescription, $commentDescription])));
                 }
 
                 if ($examples = ExamplesExtractor::make($docNode)->extract(preferString: $openApiType instanceof StringType)) {

diff --git a/tests/TypeToSchemaTransformerTest.php b/tests/TypeToSchemaTransformerTest.php
@@ -197,6 +197,25 @@
     ]);
 });
 
+it('supports simple comments descriptions in api resource', function () {
+    $transformer = new TypeTransformer($infer = app(Infer::class), $components = new Components, [JsonResourceTypeToSchema::class]);
+
+    $type = new ObjectType(ApiResourceTest_ResourceWithSimpleDescription::class);
+
+    expect($transformer->transform($type)->toArray())->toBe([
+        '$ref' => '#/components/schemas/ApiResourceTest_ResourceWithSimpleDescription',
+    ]);
+
+    expect($components->getSchema(ApiResourceTest_ResourceWithSimpleDescription::class)->toArray()['properties']['now'])->toBe([
+        'type' => 'string',
+        'description' => 'The date of the current moment.',
+    ]);
+    expect($components->getSchema(ApiResourceTest_ResourceWithSimpleDescription::class)->toArray()['properties']['now2'])->toBe([
+        'type' => 'string',
+        'description' => 'Inline comments are also supported.',
+    ]);
+});
+
 class ComplexTypeHandlersTest_SampleType extends JsonResource
 {
     public function toArray($request)
@@ -335,6 +354,21 @@ public function toArray($request)
     }
 }
 
+class ApiResourceTest_ResourceWithSimpleDescription extends JsonResource
+{
+    public function toArray($request)
+    {
+        return [
+            /**
+             * The date of the current moment.
+             */
+            'now' => now(),
+            // Inline comments are also supported.
+            'now2' => now(),
+        ];
+    }
+}
+
 enum StatusTwo: string
 {
     case DRAFT = 'draft';