feat(OpenApiType): Support comments in object array types

Signed-off-by: provokateurin <[email protected]>

Author: provokateurin

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);

src/OpenApiType.php

@@ -13,16 +13,20 @@
 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;
+use PHPStan\PhpDocParser\Ast\Type\ArrayShapeItemNode;
 use PHPStan\PhpDocParser\Ast\Type\ArrayShapeNode;
 use PHPStan\PhpDocParser\Ast\Type\ArrayTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\ConstTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\IntersectionTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\NullableTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\ObjectShapeNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
 use stdClass;
@@ -207,6 +211,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;

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 {

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."
                     }
                 }
             }

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."
                     }
                 }
             }