Improving swagger OAPI generator to mark deprecated endpoint and generating new swagger specification.

Author: krulis-martin

app/commands/GenerateSwagger.php app/commands/SwaggerGenerator.phpapp/commands/GenerateSwagger.php renamed to app/commands/SwaggerGenerator.php

@@ -16,19 +16,20 @@
     description: 'Generate an OpenAPI documentation from the temporary file created by the swagger:annotate command. '
         . 'The temporary file is deleted afterwards.'
 )]
-class GenerateSwagger extends Command
+class SwaggerGenerator extends Command
 {
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $path = __DIR__ . '/../V1Module/presenters/_autogenerated_annotations_temp.php';
 
         // check if file exists
         if (!file_exists($path)) {
-            $output->writeln("Error in GenerateSwagger: Temp annotation file not found.");
+            $output->writeln("Error in SwaggerGenerator: Temp annotation file not found.");
             return Command::FAILURE;
         }
 
-        $openapi = Generator::scan([$path]);
+        $generator = new Generator();
+        $openapi = $generator->generate([$path]);
 
         $output->writeln($openapi->toYaml());
 

app/config/config.neon

@@ -312,7 +312,6 @@ services:
 
   # commands
   - App\Console\DoctrineFixtures
-  #- App\Console\GenerateSwagger(@router)
   - App\Console\CleanupUploads
   - App\Console\CleanupExercisesFiles
   - App\Console\CleanupWorkerTmpFiles
@@ -322,7 +321,7 @@ services:
   - App\Console\GeneralStatsNotification
   - App\Console\ExportDatabase
   - App\Console\MetaConverter
-  - App\Console\GenerateSwagger
+  - App\Console\SwaggerGenerator
   - App\Console\SwaggerAnnotator
   - App\Console\CleanupLocalizedTexts
   - App\Console\CleanupExerciseConfigs

app/helpers/Swagger/AnnotationData.php

@@ -37,6 +37,12 @@ class AnnotationData
     public array $responseDataList;
     public ?string $endpointDescription;
 
+    /**
+     * @var string|null A message indicating why the endpoint is deprecated, or null if the endpoint is not deprecated.
+     *                  Empty string is valid and indicates deprecation without a message.
+     */
+    public ?string $deprecated = null;
+
     public function __construct(
         string $className,
         string $methodName,
@@ -47,6 +53,7 @@ public function __construct(
         array $fileParams,
         array $responseDataList,
         ?string $endpointDescription = null,
+        ?string $deprecated = null,
     ) {
         $this->className = $className;
         $this->methodName = $methodName;
@@ -57,6 +64,28 @@ public function __construct(
         $this->fileParams = $fileParams;
         $this->responseDataList = $responseDataList;
         $this->endpointDescription = $endpointDescription;
+        $this->deprecated = $deprecated;
+    }
+
+    private function getSummary(): ?string
+    {
+        $summary = $this->endpointDescription;
+        if ($this->deprecated !== null) {
+            $summary = $summary ?? '';
+            $summary .=  ($summary ? " " : "") . "[DEPRECATED]";
+        }
+        return $summary;
+    }
+
+    private function getDescription(): ?string
+    {
+        $description = $this->endpointDescription;
+        if ($this->deprecated !== null) {
+            $description = $description ?? '';
+            $description .=  ($description ? "\n" : "") . "[DEPRECATED]" . ($this->deprecated ? ": " : "")
+                . $this->deprecated;
+        }
+        return $description;
     }
 
     public function getAllParams(): array
@@ -219,8 +248,8 @@ public function toSwaggerAnnotations(string $route)
 
         // add the endpoint description when provided
         if ($this->endpointDescription !== null) {
-            $body->addKeyValue("summary", $this->endpointDescription);
-            $body->addKeyValue("description", $this->endpointDescription);
+            $body->addKeyValue("summary", $this->getSummary());
+            $body->addKeyValue("description", $this->getDescription());
         }
 
         foreach ($this->pathParams as $pathParam) {
@@ -255,6 +284,10 @@ public function toSwaggerAnnotations(string $route)
             $body->addValue('@OA\Response(response="200",description="Placeholder response")');
         }
 
+        if ($this->deprecated) {
+            $body->addKeyValue("deprecated", true);
+        }
+
         return $httpMethodAnnotation . $body->toString();
     }
 }

app/helpers/Swagger/AnnotationHelper.php

@@ -285,13 +285,31 @@ private static function extractAnnotationDescription(array $annotations): ?strin
         return null;
     }
 
+    /**
+     * Extracts the deprecated message from the annotations.
+     * @param array $annotations The array of annotations.
+     * @return string|null Returns the concatenated deprecated message (may be '' @deprecated without message is set)
+     *                     or null if the endpoint is not deprecated.
+     */
+    private static function extractAnnotationDeprecatedMessage(array $annotations): ?string
+    {
+        $deprecated = [];
+        foreach ($annotations as $annotation) {
+            if (str_starts_with($annotation, "@deprecated")) {
+                $deprecated[] = trim(preg_replace('/^@deprecated\s*/', '', $annotation));
+            }
+        }
+        return $deprecated ? implode("\n", array_filter($deprecated)) : null;
+    }
+
     private static function annotationParameterDataToAnnotationData(
         string $className,
         string $methodName,
         HttpMethods $httpMethod,
         array $params,
         array $responseDataList,
         ?string $description,
+        ?string $deprecated = null,
     ): AnnotationData {
         $pathParams = [];
         $queryParams = [];
@@ -322,6 +340,7 @@ private static function annotationParameterDataToAnnotationData(
             $fileParams,
             $responseDataList,
             $description,
+            $deprecated
         );
     }
 
@@ -345,14 +364,16 @@ public static function extractStandardAnnotationData(
         $httpMethod = self::extractAnnotationHttpMethod($methodAnnotations);
         $params = self::extractStandardAnnotationParams($methodAnnotations, $route);
         $description = self::extractAnnotationDescription($methodAnnotations);
+        $deprecated = self::extractAnnotationDeprecatedMessage($methodAnnotations);
 
         return self::annotationParameterDataToAnnotationData(
             $className,
             $methodName,
             $httpMethod,
             $params,
-            [], // there are no reponse params defined in the old annotations
-            $description
+            [], // there are no response params defined in the old annotations
+            $description,
+            $deprecated,
         );
     }
 
@@ -413,6 +434,7 @@ public static function extractAttributeData(string $className, string $methodNam
             return $data->toAnnotationParameterData();
         }, $attributeData);
         $description = self::extractAnnotationDescription($methodAnnotations);
+        $deprecated = self::extractAnnotationDeprecatedMessage($methodAnnotations);
 
         return self::annotationParameterDataToAnnotationData(
             $className,
@@ -421,6 +443,7 @@ public static function extractAttributeData(string $className, string $methodNam
             $params,
             $responseDataList,
             $description,
+            $deprecated,
         );
     }
 
@@ -511,7 +534,6 @@ public static function getPropertyValue(mixed $object, string $propertyName): mi
             }
         } while ($property === null && $class !== null);
 
-        $property->setAccessible(true);
         return $property->getValue($object);
     }