diff --git a/config/scramble.php b/config/scramble.php index 9001932c..dd2cee73 100644 --- a/config/scramble.php +++ b/config/scramble.php @@ -124,6 +124,15 @@ */ 'enum_cases_names_strategy' => false, + /** + * Determines whether or not Scramble will use comments above + * returns in responses to be used as the response description. + * Available options: + * - true - Comments will be ignored. + * - false - Comments will be used (default). + */ + 'ignore_response_return_comments' => false, + /** * When Scramble encounters deep objects in query parameters, it flattens the parameters so the generated * OpenAPI document correctly describes the API. Flattening deep query parameters is relevant until diff --git a/src/Support/Generator/TypeTransformer.php b/src/Support/Generator/TypeTransformer.php index 90761d06..1d7a68e0 100644 --- a/src/Support/Generator/TypeTransformer.php +++ b/src/Support/Generator/TypeTransformer.php @@ -495,12 +495,15 @@ public function toResponse(Type $type): Response|Reference|null ); } - if ($docNode = $type->getAttribute('docNode')) { + $returnCommentsShouldBeIgnored = config('scramble.ignore_response_return_comments', false); + + if (!$returnCommentsShouldBeIgnored && ($docNode = $type->getAttribute('docNode'))) { /** @var PhpDocNode $docNode */ $description = (string) Str::of($docNode->getAttribute('summary') ?: '') // @phpstan-ignore argument.type ->append("\n\n".($docNode->getAttribute('description') ?: '')) // @phpstan-ignore binaryOp.invalid ->append("\n\n".$response->description) ->trim(); + $response->description($description); $code = (int) (array_values($docNode->getTagsByName('@status'))[0]->value->value ?? $response->code ?? 200); diff --git a/tests/Support/OperationExtensions/ResponseExtensionTest.php b/tests/Support/OperationExtensions/ResponseExtensionTest.php index 6c9d49e7..85d9952d 100644 --- a/tests/Support/OperationExtensions/ResponseExtensionTest.php +++ b/tests/Support/OperationExtensions/ResponseExtensionTest.php @@ -119,3 +119,38 @@ public function toArray(\Illuminate\Http\Request $request) return ['id' => 42]; } } + +it('allows adding a comment right above the return statement to be used as the response description', function () { + $openApiDocument = generateForRoute(fn () => Route::get('api/test', ReturnCommentController_ResponseTest::class)); + + expect($responses = $openApiDocument['paths']['/test']['get']['responses']) + ->toHaveCount(1) + ->and($responses[200]['description']) + ->toBe('This description comes from a comment'); +}); +class ReturnCommentController_ResponseTest +{ + public function __invoke() + { + // This description comes from a comment + return something_unknown(); + } +} + +it('allows ignores a comment right above the return statement to be used as the response description if is disabled in configuration', function () { + config()->set('scramble.ignore_response_return_comments', true); + $openApiDocument = generateForRoute(fn () => Route::get('api/test', ReturnCommentWithOptionDisabledController_ResponseTest::class)); + + expect($responses = $openApiDocument['paths']['/test']['get']['responses']) + ->toHaveCount(1) + ->and($responses[200]['description']) + ->toBe(''); +}); +class ReturnCommentWithOptionDisabledController_ResponseTest +{ + public function __invoke() + { + // This description comes from a comment + return something_unknown(); + } +}