Tidy docs

Author: lachiebol

Annotations/AnnotationGenerator.php

@@ -121,15 +121,15 @@ public function generatePluginApiAnnotations(string $pluginName, bool $writeToFi
         $pluginMetadata = Proxy::getInstance()->getMetadata()[$className] ?? [];
 
         $annotations = [[sprintf('@OA\Tag(name="%s")', $pluginName)]];
-        // I decided to not include the description in the tag annotation so that it automatically pulls the API class comment as the description.
-//        if (!empty($pluginMetadata['__documentation'])) {
-//            $tagLines = $this->buildLinesForAnnotationObject('@OA\Tag', [
-//                sprintf('name="%s"', $pluginName),
-//                sprintf('description="%s"', $this->normaliseDescriptionText($pluginMetadata['__documentation'])),
-//            ]);
-//            $this->removeTrailingCommaFromLastLine($tagLines);
-//            $annotations[] = $tagLines;
-//        }
+//      I decided to not include the description in the tag annotation so that it automatically pulls the API class comment as the description.
+        if (!empty($pluginMetadata['__documentation'])) {
+            $tagLines = $this->buildLinesForAnnotationObject('@OA\Tag', [
+                sprintf('name="%s"', $pluginName),
+                sprintf('description="%s"', $this->normaliseDescriptionText($pluginMetadata['__documentation'])),
+            ]);
+            $this->removeTrailingCommaFromLastLine($tagLines);
+            $annotations[] = $tagLines;
+        }
 
         foreach (array_keys($pluginMetadata) as $metadataMethod) {
             if (!$reflectionClass->hasMethod($metadataMethod)) {
@@ -254,11 +254,12 @@ protected function buildAnnotationForMethod(array $rules, string $pluginName, \R
 
         $params = $this->determineParameters($rules, $pluginName, $methodName, $reflectionMethod);
         $responses = $this->determineResponses($rules, $pluginName, $methodName, $reflectionMethod, $params);
+        $description = $this->determineDescription($pluginName, $methodName, $reflectionMethod);
 
         $isPost = !empty($rules['plugins'][$pluginName]['methodsRequiringPost'])
             && in_array($methodName, $rules['plugins'][$pluginName]['methodsRequiringPost']);
 
-        return $this->compileOperationLines($path, $opId, $pluginName, $params, $responses, $isPost);
+        return $this->compileOperationLines($path, $opId, $pluginName, $params, $responses, $description, $isPost);
     }
 
     /**
@@ -354,6 +355,24 @@ public function getResponseInfoFromDocBlock(string $docBlock): array
     }
 
     /**
+     * Extract the description/summary from a given docblock
+     *
+     * @param string $docBlock The comment block from a method, which hopefully contains a description.
+     *
+     * @return string Description/summary extracted from the docblock
+     */
+    public function getDescriptionFromDocBlock(string $docBlock): string
+    {
+        $factory = DocBlockFactory::createInstance();
+        $docBlockObject = $factory->create($docBlock);
+
+        return $docBlockObject->getSummary();
+    }
+
+
+
+
+        /**
      * This is a helper method for building the path used for an operation annotation. It takes a path template, like
      * the one from the config array and populates it with the plugin name and API method name.
      *
@@ -578,6 +597,30 @@ protected function determineParameters(array $rules, string $plugin, string $met
         ];
     }
 
+
+
+
+    /**
+     * Get the description/summary of a given method
+     *
+     * @param string $plugin Name of the plugin. E.g. TagManager.
+     * @param string $method The name of the method being annotated.
+     * @param \ReflectionMethod $reflectionMethod The reflective representation of the method to provide metadata.
+     *
+     * @return string Description of the method
+     */
+    protected function determineDescription(string $plugin, string $method, \ReflectionMethod $reflectionMethod): string
+    {
+        $description = '';
+        $docBlock = $reflectionMethod->getDocComment();
+        if (!empty($docBlock)) {
+            $description = $this->getDescriptionFromDocBlock($docBlock);
+        }
+
+        return $description;
+    }
+
+
     /**
      * Map the PHP type to the OpenAPI type. The currently available types for v3.1.1 are the following: “null”,
      * “boolean”, “object”, “array”, “number”, “string”, or “integer”.
@@ -1717,12 +1760,13 @@ public function buildSchemaObjectArrays(array $typesMap, string $default = '', s
      *
      * @return string[] The array of all the lines of the operation annotation object.
      */
-    public function compileOperationLines(string $path, string $opId, string $plugin, array $params, array $responses, bool $isPost = false): array
+    public function compileOperationLines(string $path, string $opId, string $plugin, array $params, array $responses, string $description, bool $isPost = false): array
     {
         $operationValuesMap = [
             'path="' . $path . '"',
             'operationId="' . $opId . '"',
             'tags={"' . $plugin . '"}',
+            'description="' . $description . '"',
         ];
         foreach ($params['refs'] ?? [] as $ref) {
             $operationValuesMap[] = '@OA\Parameter(ref="' . $ref . '")';

Specs/SpecGenerator.php

@@ -73,17 +73,18 @@ public function generateSpec(array $pluginNames, string $format = 'json', string
             Manager::getInstance()->checkIsPluginActivated($pluginName);
 
             $pluginDir = Manager::getInstance()::getPluginDirectory($pluginName);
-            $pluginAnnotationsSource = $pluginDir . '/API.php';
+//            $pluginAnnotationsSource = $pluginDir . '/API.php';
+            $pluginAnnotationsSource = $currentPluginDir . '/tmp/annotations/' . $pluginName . 'GeneratedAnnotations.php';
             try {
                 $openapi = (new Generator(StaticContainer::get(NullLogger::class)))->generate([
                     $pluginAnnotationsSource,
                 ]);
             } catch (\Throwable $e) {
                 throw new \Exception('There was an error testing the API annotations for plugin ' . $pluginName, 0, $e);
             }
-            if (trim($openapi->toYaml()) === 'openapi: ' . OpenApi::DEFAULT_VERSION) {
-                throw new \Exception("The $pluginName plugin's API class does not appear to be annotated yet.");
-            }
+//            if (trim($openapi->toYaml()) === 'openapi: ' . OpenApi::DEFAULT_VERSION) {
+//                throw new \Exception("The $pluginName plugin's API class does not appear to be annotated yet.");
+//            }
             $pluginDirs[$pluginName] = $pluginAnnotationsSource;
         }