OpenAPITools / OpenAPITools/openapi-generator
[REQ] Add @return annotation to StrictJsonDeserializationVisitor to avoid deprecated logs
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Is your feature request related to a problem? Please describe.
When generating PHP code using OpenAPI Generator, some generated classes trigger deprecated warnings related to missing or incomplete @return annotations.
This happens with recent PHP versions (8.3) and Symfony (7.3) environments using JMS Serializer, where interfaces may introduce native return types in future versions.
Because the generated implementations do not explicitly declare return types or PHPDoc @return annotations, Symfony's DebugClassLoader emits deprecation warnings at runtime.
Example of the warning:
User Deprecated: Method "JMS\Serializer\Visitor\DeserializationVisitorInterface::visitNull()"
might add "null" as a native return type declaration in the future.
Do the same in implementation "...StrictJsonDeserializationVisitor" now
to avoid errors or add an explicit @return annotation to suppress this message.
Describe the solution you'd like
OpenAPI Generator should add explicit @return annotations in generated PHP methods when the return type is already known.
Adding proper PHPDoc return annotations prevents Symfony/JMS Serializer deprecation warnings and improves forward compatibility with future PHP native return types.
For example, adding annotations like:
/**
* {@inheritdoc}
*
* @return null
*/
public function visitNull($data, array $type): null
{
return $this->jsonDeserializationVisitor->visitNull($data, $type);
}
/**
* {@inheritdoc}
*
* @return mixed
*/
public function getResult($data): mixed
{
return $this->jsonDeserializationVisitor->getResult($data);
}
/**
* {@inheritdoc}
*
* @return mixed
*/
public function visitProperty(PropertyMetadata $metadata, $data): mixed
{
return $this->jsonDeserializationVisitor->visitProperty($metadata, $data);
}
/**
* {@inheritdoc}
*
* @return mixed
*/
public function getResult($data): mixed
{
return $this->jsonDeserializationVisitor->getResult($data);
}
---
## Describe alternatives you've considered
I tested locally by manually adding the missing @return annotations inside
StrictJsonDeserializationVisitor.
After adding these annotations, the deprecation logs completely disappeared.
However, this workaround requires manually patching generated code after each generation or maintaining custom templates, which defeats the purpose of automated code generation.
---
## Additional context
User Deprecated: Method "JMS\Serializer\Visitor\DeserializationVisitorInterface::visitNull()"
might add "null" as a native return type declaration in the future.
After adding explicit @return annotations, these warnings no longer appear.
Handling this directly in the PHP generator templates would improve compatibility
with modern PHP environments and reduce deprecated runtime warnings without
changing runtime behavior.
My environnement :
- openApi 7.17.0 : file StrictJsonDeserializationVisitor didn't change in master
- php 8.3
- Symfony 7.3
- Generator : PHP (Rest)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the generated StrictJsonDeserializationVisitor in the PHP (Rest) generator and compare its methods with the JMS Serializer interface methods named in the report. Trace the corresponding PHP generator templates, add the requested return annotations, and verify that generation under PHP 8.3 and Symfony 7.3 no longer emits the reported deprecation warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100