From 1b00445996dcd36d4fa1dc8b54cb9eb74d857c5f Mon Sep 17 00:00:00 2001 From: Alexis Degrugillier Date: Wed, 20 Aug 2025 16:30:23 -0400 Subject: [PATCH] Add deprecation date support Before, the deprecation badge was just a boolean. Now it can be used both as a boolean and a string. With a string, the badge is enhanced with said string to add some context. This does not work with external resources since the OpenAPI specification accepts only a boolean value. Fix #1018 --- camel/Extraction/Metadata.php | 2 +- camel/Output/OutputEndpointData.php | 5 ----- .../components/badges/deprecated.blade.php | 4 +++- .../views/themes/default/endpoint.blade.php | 2 +- .../views/themes/elements/endpoint.blade.php | 8 +++++++- src/Attributes/Deprecated.php | 2 +- .../Strategies/Metadata/GetFromDocBlocks.php | 10 +++++++--- .../Metadata/GetFromDocBlocksTest.php | 19 +++++++++++++++++++ .../GetFromMetadataAttributesTest.php | 17 +++++++++++++++++ 9 files changed, 56 insertions(+), 13 deletions(-) diff --git a/camel/Extraction/Metadata.php b/camel/Extraction/Metadata.php index c784ce92..4d088b82 100644 --- a/camel/Extraction/Metadata.php +++ b/camel/Extraction/Metadata.php @@ -13,5 +13,5 @@ class Metadata extends BaseDTO public ?string $title; public ?string $description; public bool $authenticated = false; - public bool $deprecated = false; + public bool|string $deprecated = false; } diff --git a/camel/Output/OutputEndpointData.php b/camel/Output/OutputEndpointData.php index 971fdc03..ca8a360e 100644 --- a/camel/Output/OutputEndpointData.php +++ b/camel/Output/OutputEndpointData.php @@ -313,11 +313,6 @@ public function isAuthed(): bool return $this->metadata->authenticated; } - public function isDeprecated(): bool - { - return $this->metadata->deprecated; - } - public function hasJsonBody(): bool { if ($this->hasFiles() || empty($this->nestedBodyParameters)) diff --git a/resources/views/components/badges/deprecated.blade.php b/resources/views/components/badges/deprecated.blade.php index 0db49c7f..97f76e44 100644 --- a/resources/views/components/badges/deprecated.blade.php +++ b/resources/views/components/badges/deprecated.blade.php @@ -1,3 +1,5 @@ -@if($deprecated)@component('scribe::components.badges.base', ['colour' => "darkgoldenrod", 'text' => 'deprecated']) +@if($deprecated !== false) +@php($text = $deprecated === true ? 'deprecated' : "deprecated:$deprecated") +@component('scribe::components.badges.base', ['colour' => 'darkgoldenrod', 'text' => $text]) @endcomponent @endif diff --git a/resources/views/themes/default/endpoint.blade.php b/resources/views/themes/default/endpoint.blade.php index 09497e7d..af29e103 100644 --- a/resources/views/themes/default/endpoint.blade.php +++ b/resources/views/themes/default/endpoint.blade.php @@ -8,7 +8,7 @@

@component('scribe::components.badges.auth', ['authenticated' => $endpoint->isAuthed()]) @endcomponent -@component('scribe::components.badges.deprecated', ['deprecated' => $endpoint->isDeprecated()]) +@component('scribe::components.badges.deprecated', ['deprecated' => $endpoint->metadata->deprecated]) @endcomponent

diff --git a/resources/views/themes/elements/endpoint.blade.php b/resources/views/themes/elements/endpoint.blade.php index 9c10d8bc..15445d64 100644 --- a/resources/views/themes/elements/endpoint.blade.php +++ b/resources/views/themes/elements/endpoint.blade.php @@ -37,12 +37,18 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{!! rtrim($baseUrl, '/') >requires authentication @endif - @if($endpoint->metadata->deprecated) + @if($endpoint->metadata->deprecated === true)
deprecated
@endif + @if(is_string($endpoint->metadata->deprecated)) +
deprecated:{{$endpoint->metadata->deprecated}} +
+ @endif diff --git a/src/Attributes/Deprecated.php b/src/Attributes/Deprecated.php index 2d20058b..b7d5850d 100644 --- a/src/Attributes/Deprecated.php +++ b/src/Attributes/Deprecated.php @@ -8,7 +8,7 @@ class Deprecated { public function __construct( - public ?bool $deprecated = true, + public bool|string|null $deprecated = true, ) { } diff --git a/src/Extracting/Strategies/Metadata/GetFromDocBlocks.php b/src/Extracting/Strategies/Metadata/GetFromDocBlocks.php index 6426ed04..eef3d68f 100644 --- a/src/Extracting/Strategies/Metadata/GetFromDocBlocks.php +++ b/src/Extracting/Strategies/Metadata/GetFromDocBlocks.php @@ -54,15 +54,19 @@ protected function getAuthStatusFromDocBlock(DocBlock $methodDocBlock, ?DocBlock : null; } - protected function getDeprecatedStatusFromDocBlock(DocBlock $methodDocBlock, ?DocBlock $classDocBlock = null): bool + protected function getDeprecatedStatusFromDocBlock(DocBlock $methodDocBlock, ?DocBlock $classDocBlock = null): bool|string { foreach ($methodDocBlock->getTags() as $tag) { if (strtolower($tag->getName()) === 'deprecated') { - return true; + return $tag->getContent() === '' ? true : $tag->getContent(); } } - return $classDocBlock && $this->getDeprecatedStatusFromDocBlock($classDocBlock); + if ($classDocBlock instanceof DocBlock) { + return $this->getDeprecatedStatusFromDocBlock($classDocBlock); + } + + return false; } /** diff --git a/tests/Strategies/Metadata/GetFromDocBlocksTest.php b/tests/Strategies/Metadata/GetFromDocBlocksTest.php index 9d9e592a..a4026fe2 100644 --- a/tests/Strategies/Metadata/GetFromDocBlocksTest.php +++ b/tests/Strategies/Metadata/GetFromDocBlocksTest.php @@ -83,6 +83,25 @@ public function can_fetch_metadata_from_method_and_class() $this->assertSame('', $results['groupDescription']); $this->assertSame('Endpoint title.', $results['title']); $this->assertSame("", $results['description']); + + $classDocblock = <<getMetadataFromDocBlock(new DocBlock($methodDocblock), new DocBlock($classDocblock)); + + $this->assertTrue($results['authenticated']); + $this->assertSame('2025-01-01', $results['deprecated']); + $this->assertSame(null, $results['groupName']); + $this->assertSame('Scheiße', $results['subgroup']); + $this->assertSame('Heilige Scheiße', $results['subgroupDescription']); + $this->assertSame('', $results['groupDescription']); + $this->assertSame('Endpoint title.', $results['title']); + $this->assertSame("", $results['description']); } /** @test */ diff --git a/tests/Strategies/Metadata/GetFromMetadataAttributesTest.php b/tests/Strategies/Metadata/GetFromMetadataAttributesTest.php index 64318ae3..1eda2e27 100644 --- a/tests/Strategies/Metadata/GetFromMetadataAttributesTest.php +++ b/tests/Strategies/Metadata/GetFromMetadataAttributesTest.php @@ -144,6 +144,15 @@ public function can_fetch_from_authenticated_attribute_or_authenticated_paramete $this->assertArraySubset([ "deprecated" => true, ], $results); + + $endpoint = $this->endpoint(function (ExtractedEndpointData $e) { + $e->controller = new ReflectionClass(MetadataAttributesTestController6::class); + $e->method = $e->controller->getMethod('c1'); + }); + $results = $this->fetch($endpoint); + $this->assertArraySubset([ + "deprecated" => "2023-01-01", + ], $results); } protected function fetch($endpoint): array @@ -240,3 +249,11 @@ public function c1() { } } + +#[Deprecated("2023-01-01")] +class MetadataAttributesTestController6 +{ + public function c1() + { + } +}