From bbfa4cb9daaf2d1cebe2bccab73559ef83540031 Mon Sep 17 00:00:00 2001 From: provokateurin Date: Wed, 5 Mar 2025 13:20:07 +0100 Subject: [PATCH] feat(OpenApiType): Support comments in object array types Signed-off-by: provokateurin --- generate-spec.php | 2 +- src/OpenApiType.php | 6 ++++++ tests/lib/ResponseDefinitions.php | 5 +++++ tests/openapi-full.json | 13 ++++++++++--- tests/openapi.json | 13 ++++++++++--- 5 files changed, 32 insertions(+), 7 deletions(-) diff --git a/generate-spec.php b/generate-spec.php index 754d1dc..6685319 100755 --- 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 index b1a3ff8..2d1322c 100644 --- 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 index cad6d92..c37f73b 100644 --- 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 index 8ca9f22..1af6e05 100644 --- 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 index 8e369de..bac0f19 100644 --- 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." } } }