Routes can be marked as deprecated (#994)

Author: s-shiryaev

camel/Extraction/Metadata.php

@@ -13,4 +13,5 @@ class Metadata extends BaseDTO
     public ?string $title;
     public ?string $description;
     public bool $authenticated = false;
+    public bool $deprecated = false;
 }

camel/Output/OutputEndpointData.php

@@ -313,6 +313,11 @@ 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))

resources/css/theme-default.style.css

@@ -1037,6 +1037,10 @@ html {
     background-color: green;
 }
 
+.badge.badge-darkgoldenrod {
+    background-color: darkgoldenrod;
+}
+
 .badge.badge-darkgreen {
     background-color: darkgreen;
 }

resources/views/components/badges/deprecated.blade.php

@@ -0,0 +1,3 @@
+@if($deprecated)@component('scribe::components.badges.base', ['colour' => "darkgoldenrod", 'text' => 'deprecated'])
+@endcomponent
+@endif

resources/views/themes/default/endpoint.blade.php

@@ -8,6 +8,8 @@
 <p>
 @component('scribe::components.badges.auth', ['authenticated' => $endpoint->isAuthed()])
 @endcomponent
+@component('scribe::components.badges.deprecated', ['deprecated' => $endpoint->isDeprecated()])
+@endcomponent
 </p>
 
 {!! Parsedown::instance()->text($endpoint->metadata->description ?: '') !!}

resources/views/themes/elements/endpoint.blade.php

@@ -37,6 +37,12 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{{ rtrim($baseUrl, '/') }
                             >requires authentication
                             </div>
                         @endif
+                        @if($endpoint->metadata->deprecated)
+                            <div class="sl-font-prose sl-font-semibold sl-px-1.5 sl-py-0.5 sl-text-on-primary sl-rounded-lg"
+                                 style="background-color: darkgoldenrod"
+                            >deprecated
+                            </div>
+                        @endif
             </div>
         </div>
 

src/Attributes/Deprecated.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Knuckles\Scribe\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_FUNCTION | Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
+class Deprecated
+{
+    public function __construct(
+        public ?bool $deprecated = true,
+    )
+    {
+    }
+
+    public function toArray()
+    {
+        return ["deprecated" => $this->deprecated];
+    }
+}

src/Extracting/Strategies/Metadata/GetFromDocBlocks.php

@@ -29,6 +29,7 @@ public function getMetadataFromDocBlock(DocBlock $methodDocBlock, DocBlock $clas
             'subgroupDescription' => $this->getEndpointSubGroupDescription($methodDocBlock, $classDocBlock),
             'title' => $title ?: $methodDocBlock->getShortDescription(),
             'description' => $methodDocBlock->getLongDescription()->getContents(),
+            'deprecated' => $this->getDeprecatedStatusFromDocBlock($methodDocBlock, $classDocBlock),
         ];
         if (!is_null($authStatus = $this->getAuthStatusFromDocBlock($methodDocBlock, $classDocBlock))) {
             $metadata['authenticated'] = $authStatus;
@@ -53,6 +54,17 @@ protected function getAuthStatusFromDocBlock(DocBlock $methodDocBlock, ?DocBlock
             : null;
     }
 
+    protected function getDeprecatedStatusFromDocBlock(DocBlock $methodDocBlock, ?DocBlock $classDocBlock = null): bool
+    {
+        foreach ($methodDocBlock->getTags() as $tag) {
+            if (strtolower($tag->getName()) === 'deprecated') {
+                return true;
+            }
+        }
+
+        return $classDocBlock && $this->getDeprecatedStatusFromDocBlock($classDocBlock);
+    }
+
     /**
      * @return array The endpoint's group name, the group description, and the endpoint title
      */

src/Extracting/Strategies/Metadata/GetFromMetadataAttributes.php

@@ -4,6 +4,7 @@
 
 use Knuckles\Camel\Extraction\ExtractedEndpointData;
 use Knuckles\Scribe\Attributes\Authenticated;
+use Knuckles\Scribe\Attributes\Deprecated;
 use Knuckles\Scribe\Attributes\Endpoint;
 use Knuckles\Scribe\Attributes\Group;
 use Knuckles\Scribe\Attributes\Subgroup;
@@ -24,6 +25,7 @@ class GetFromMetadataAttributes extends PhpAttributeStrategy
         Endpoint::class,
         Authenticated::class,
         Unauthenticated::class,
+        Deprecated::class,
     ];
 
     protected function extractFromAttributes(

src/Writing/OpenApiSpecGenerators/BaseGenerator.php

@@ -52,6 +52,10 @@ public function pathItem(array $pathItem, array $groupedEndpoints, OutputEndpoin
             })['name']],
         ];
 
+        if ($endpoint->metadata->deprecated) {
+            $spec['deprecated'] = true;
+        }
+
         if (count($endpoint->bodyParameters)) {
             $spec['requestBody'] = $this->generateEndpointRequestBodySpec($endpoint);
         }
@@ -549,7 +553,7 @@ public function generateSchemaForResponseValue(mixed $value, OutputEndpointData
                 $schema['items']['properties'] = collect($sample)->mapWithKeys(function ($v, $k) use ($endpoint, $path) {
                     return [$k => $this->generateSchemaForResponseValue($v, $endpoint, "$path.$k")];
                 })->toArray();
-                
+
                 $required = $this->filterRequiredResponseFields($endpoint, array_keys($schema['items']['properties']),
                     $path);
                 if ($required) {