$deprecationReason is not actually displayed in the API Doc (SwaggerUI / ReDoc)

[algorun77]

API Platform version(s) affected: 3.4.10

Description
Hello, I've had some issues with using the deprecation system.
According to the documentation, it is possible to mark a property/operation/resource as deprecated using the parameter deprecationReason. However, it's a bit unclear if the reason itself is supposed to be displayed or not. The documentation explicitly shows that it should be the case for GraphQL, displaying a screenshot, but simply states this :

• With JSON-lD / Hydra, an owl:deprecated annotation property will be added to the appropriate data structure
• With Swagger / OpenAPI, a deprecated property will be added
• With GraphQL, the isDeprecated and deprecationReason properties will be added to the schema

However, using SwaggerUI and ReDoc, I cannot get the actual reason from the deprecationReason property.

• With JSON-lD, The owl:deprecated annotation property is just a boolean
• With SwaggerUI, it simply states : "Warning: Deprecated"
• I couldn't verify GraphQL because I was unable to make it work but I trust the documentation

I find this behavior very strange because what's the point in specifying the deprecation reason if it is not used, or only as a boolean?

How to reproduce
Simply setup a new project :

1. Run `symfony new apip-deprecation-test --version="6.4.*" (tested with Sf 6.4)
2. Install some Composer dependencies, like : api-platform/core:3.4.10, api-platform/graphql, doctrine/orm, symfony/asset, symfony/twig-bundle
3. Create a simple Entity, and mark some Operations/Properties as deprecated using deprecationReason :

<?php

namespace App\Entity;

use ApiPlatform\Metadata\{
    ApiResource,
    ApiProperty,
    Get,
    GetCollection,
    Put
};
use App\Repository\DummyRepository;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity(repositoryClass: DummyRepository::class)]
#[ApiResource]
#[Get(deprecationReason: "Something isn't right here")]
#[GetCollection()]
#[Put(deprecationReason: 'Use PATCH instead')]
class Dummy
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    #[ApiProperty(deprecationReason: "Use the 'newValue' instead")]
    private ?string $oldValue = null;

    #[ORM\Column(length: 255)]
    private ?string $newValue = null;

    public function getId(): ?int
    {
        return $this->id;
    }

    // Accessors/Mutators methods
}

4. Run the server using symfony server:start and connect to the API Doc at https://127.0.0.1:8000/api (or equivalent URI based on your own config)
5. Documentation in SwaggerUI will only show a tag with Deprecated and write Warning: Deprecated. ReDoc will only show a tag. JSON-lD will display a owl:deprecated: true property. But the actual message filled in deprecationReason will never be shown.

Possible Solution
It's quite confusing to be allowed to input a string for the deprecationReason property only to never be able to actually show it to the users of the API Documentation. It could be important to explain why a property/operation/resource is being deprecated and how to update the code accordingly. So I have the following suggestions:

• Add the message to the documentation. For instance with SaggerUI, instead of "Warning: Deprecated.", write "Warning: Deprecated. . This would be the best option.
• Change the ?string $deprecationReason = null by bool $deprecated = false, this is straightforward and reflects the actual behavior. This is the worst option since it would be a BC and demand time to replace everything in the codebase.
• Update the documentation to be more precise about the actual behavior of deprecationReason, by explaining that the reason will not be wrote for SwaggerUI, ReDoc and JSON-lD. This is the easiest solution, but it would still mean that the text in deprecationReason is pretty useless

Additional Context
Here are the screenshots from the generated API Documentation based on a simple project:

SwaggerUI :

ReDoc:

JSON-lD:

I hope I've been understanding things correctly.
Thanks !

[soyuka]

There's only a deprecated field inside open api I don't see any way to output the reason.

[ostrolucky]

Yep. It's not supposed to be displayed (well it would if there was a way to do it in spec). It's still useful though when looking through the code.