swagger-php: Wrong docs generation for php8 promoted properties.
Using php 8 promoted properties, I expect the doccomment to be parsed the same as for the basic class properties. But it actually looks like they are overridden by method arguments. As far as I’m concerned, the only reason I want to use elevated properties is the linter hints (and one more, but it’s affected by the class extension). I tried to investigate on my own but was unsuccessful. Maybe someone also wants to use PP like me and this could be a nice fix. In my opinion, the problem is overriding because ReflectionClass->getProperties() returns two values with the correct doc comments.
Code:
#[Schema()]
class NameValue
{
/**
* Property name.
*
* @var string
*/
#[Property()]
public string $name = '';
public function __construct(
/**
* Property value.
*
* @var string
*/
#[Property()]
public string $value = '',
) {
}
}
Expected result:
"NameValue": {
"properties": {
"value": {
"description": "Property value.",
"type": "string",
"nullable": false
},
"name": {
"description": "Property name.",
"type": "string"
}
},
"type": "object"
},
Actual result:
"NameValue": {
"properties": {
"value": {
"type": "string",
"nullable": false
},
"name": {
"description": "Property name.",
"type": "string"
}
},
"type": "object"
},
About this issue
- Original URL
- State: closed
- Created 4 years ago
- Comments: 17 (2 by maintainers)
I’m pretty sure I’m encountering this same issue, and have a working theory as to why it happens.
In
ReflectionAnalyzer:129it loops through methods, and creates a context for that method. It then invokesAttributeAnnotationFactory@buildwhich will loop through the method arguments, and attach docblocks to these.https://github.com/zircote/swagger-php/blob/ce3b9be639918cc0b1eed5e24869a72f8a2ca357/src/Analysers/ReflectionAnalyser.php#L129-L142
It just so happens, that
__construct()is also a method, and in the case it of promoted properties it will build the properties through the constructor arguments, instead of through the properties themselves. There is a hint in AttributeAnnotationFactory:34`:https://github.com/zircote/swagger-php/blob/ce3b9be639918cc0b1eed5e24869a72f8a2ca357/src/Analysers/AttributeAnnotationFactory.php#L34-L37
The problem is, that normally each property will have its own context. But because promoted properties are handled as method arguments, they all share the same method context. So for each promoted property, it actually just overwrites the previous docblock, and only the last one will be used.
As a proof of concept, I added the following line on
AttributeAnnotationFactory:83, and the bug indeed disappeared.Whether this is a good fix or not, I’m not sure. But at least I hope it sheds some light on the issue.
I’m hoping someone with more knowledge on the inner workings will help create a proper bug fix.
Unfortunately I was failed to create fully isolated project, but the problem could be reproduced just with one model.
In docs, for this model, comments will be messed up.
If I can help in any other way, please, let me know.