feat(OpenApiType): Support comments in object array types

Signed-off-by: provokateurin <kate@provokateurin.de>
nextcloud · Mar 5, 2025 · bbfa4cb · bbfa4cb
1 parent 40acce7
commit bbfa4cb
Show file tree

Hide file tree

Showing 5 changed files with 32 additions and 7 deletions.
diff --git a/generate-spec.php b/generate-spec.php
@@ -70,7 +70,7 @@
 $astParser = (new ParserFactory())->createForNewestSupportedVersion();
 $nodeFinder = new NodeFinder;
 
-$config = new ParserConfig(usedAttributes: ['lines' => true, 'indexes' => true]);
+$config = new ParserConfig(usedAttributes: ['lines' => true, 'indexes' => true, 'comments' => true]);
 $lexer = new Lexer($config);
 $constExprParser = new ConstExprParser($config);
 $typeParser = new TypeParser($config, $constExprParser);

diff --git a/src/OpenApiType.php b/src/OpenApiType.php
@@ -13,6 +13,8 @@
 use PhpParser\Node\NullableType;
 use PhpParser\Node\UnionType;
 use PhpParser\NodeAbstract;
+use PHPStan\PhpDocParser\Ast\Attribute;
+use PHPStan\PhpDocParser\Ast\Comment;
 use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprIntegerNode;
 use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprStringNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
@@ -207,6 +209,10 @@ public static function resolve(string $context, array $definitions, ParamTagValu
 			foreach ($node->items as $item) {
 				$name = $item->keyName instanceof ConstExprStringNode ? $item->keyName->value : $item->keyName->name;
 				$type = self::resolve($context . ': ' . $name, $definitions, $item->valueType);
+				$comments = array_map(static fn (Comment $comment) => preg_replace('/^\/\/\s*/', '', $comment->text), $item->keyName->getAttribute(Attribute::COMMENTS) ?? []);
+				if ($comments !== []) {
+					$type->description = implode("\n", $comments);
+				}
 				$properties[$name] = $type;
 				if (!$item->optional) {
 					$required[] = $name;

diff --git a/tests/lib/ResponseDefinitions.php b/tests/lib/ResponseDefinitions.php
@@ -56,8 +56,13 @@
  * }
  *
  * @psalm-type NotificationsRequestProperty = array{
+ *     // A comment.
  *     publicKey: string,
+ * 	   // A comment with a link: https://example.com.
  *     signature: string,
+ *     // A comment.
+ *     // Another comment.
+ *     multipleComments: string,
  * }
  */
 class ResponseDefinitions {

diff --git a/tests/openapi-full.json b/tests/openapi-full.json
@@ -255,14 +255,21 @@
                 "type": "object",
                 "required": [
                     "publicKey",
-                    "signature"
+                    "signature",
+                    "multipleComments"
                 ],
                 "properties": {
                     "publicKey": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "A comment."
                     },
                     "signature": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "A comment with a link: https://example.com."
+                    },
+                    "multipleComments": {
+                        "type": "string",
+                        "description": "A comment. Another comment."
                     }
                 }
             }

diff --git a/tests/openapi.json b/tests/openapi.json
@@ -222,14 +222,21 @@
                 "type": "object",
                 "required": [
                     "publicKey",
-                    "signature"
+                    "signature",
+                    "multipleComments"
                 ],
                 "properties": {
                     "publicKey": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "A comment."
                     },
                     "signature": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "A comment with a link: https://example.com."
+                    },
+                    "multipleComments": {
+                        "type": "string",
+                        "description": "A comment. Another comment."
                     }
                 }
             }