OpenAPITools / OpenAPITools/openapi-generator

[REQ] Add @return annotation to StrictJsonDeserializationVisitor to avoid deprecated logs

Open
#23,068 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.