OpenAPI Gen: @link tag, examples for known params

inc/Remote/ApiCall.php

@@ -26,6 +26,9 @@ class ApiCall
     /** @var string The description of the method */
     protected string $description = '';
 
+    /** @var array[] The parsed tags */
+    protected $tags;
+
     /**
      * Make the given method available as an API call
      *
@@ -175,6 +178,30 @@ class ApiCall
         return $this;
     }
 
+    /**
+     * Returns the docblock tags that have not been processed specially
+     *
+     * @return array[]
+     */
+    public function getTags()
+    {
+        return $this->tags;
+    }
+
+    /**
+     * Returns any data that is available in the given docblock tag
+     *
+     * @param string $tag
+     * @return string[] returns an empty array if no such tags exists
+     */
+    public function getTag($tag)
+    {
+        if(isset($this->tags[$tag])) {
+            return $this->tags[$tag];
+        }
+        return [];
+    }
+
     /**
      * Fill in the metadata
      *
@@ -193,6 +220,7 @@ class ApiCall
         $docInfo = $this->parseDocBlock($reflect->getDocComment());
         $this->summary = $docInfo['summary'];
         $this->description = $docInfo['description'];
+        $this->tags = $docInfo['tags'];
 
         foreach ($reflect->getParameters() as $parameter) {
             $name = $parameter->name;

inc/Remote/OpenAPIGenerator.php

@@ -3,6 +3,8 @@
 
 namespace dokuwiki\Remote;
 
+use dokuwiki\Utf8\PhpString;
+
 class OpenAPIGenerator
 {
 
@@ -81,10 +83,19 @@ class OpenAPIGenerator
         $retType = $this->fixTypes($call->getReturn()['type']);
         $retExample = $this->generateExample('result', $retType);
 
+        $description = $call->getDescription();
+        $links = $call->getTag('link');
+        if ($links) {
+            $description .= "\n\n**See also:**";
+            foreach ($links as $link) {
+                $description .= "\n\n* " . $this->generateLink($link);
+            }
+        }
+
         return [
             'operationId' => $method,
             'summary' => $call->getSummary(),
-            'description' => $call->getDescription(),
+            'description' => $description,
             'requestBody' => [
                 'required' => true,
                 'content' => [
@@ -151,7 +162,7 @@ class OpenAPIGenerator
             $props[$name] = [
                 'type' => $type,
                 'description' => $info['description'],
-                'examples' => [ $example ],
+                'examples' => [$example],
             ];
         }
         return $schema;
@@ -182,11 +193,33 @@ class OpenAPIGenerator
             case 'boolean':
                 return true;
             case 'string':
-                return 'some-'.$name;
+                if($name === 'page') return 'playground:playground';
+                if($name === 'media') return 'wiki:dokuwiki-128.png';
+                return 'some-' . $name;
             case 'array':
-                return ['some-'.$name, 'other-'.$name];
+                return ['some-' . $name, 'other-' . $name];
             default:
                 return new \stdClass();
         }
     }
+
+    /**
+     * Generates a markdown link from a dokuwiki.org URL
+     *
+     * @param $url
+     * @return mixed|string
+     */
+    protected function generateLink($url)
+    {
+        if (preg_match('/^https?:\/\/(www\.)?dokuwiki\.org\/(.+)$/', $url, $match)) {
+            $name = $match[2];
+
+            $name = str_replace(['_', '#', ':'], [' ', ' ', ' '], $name);
+            $name = PhpString::ucwords($name);
+
+            return "[$name]($url)";
+        } else {
+            return $url;
+        }
+    }
 }