diff --git a/src/Support/Generator/TypeTransformer.php b/src/Support/Generator/TypeTransformer.php index 6ef24616..07b599bd 100644 --- 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 index 5a80e453..feeb17b4 100644 --- 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';