NelmioApiDocBundle et formulaire

Bonjour à tous,

Je souhaite réaliser et documenter une petite API REST, j’utilise pour ce faire symfony 4.4 et NelmioApiDocBundle.
Je trouve que ce bundle ne dispose pas d’une bonne documentation (un comble pour un outil permettant de générer une documentation) en ce sens où je n’ai trouvé que 2 exemples sur le site de symfony… il existe bien une documentation complète sur OpenAPI, le standard sur lequel repose le bundle mais moi ce que je souhaite c’est l’utiliser concrètement dans mon projet symfony.

J’ai un controller basique, pour documenter le résultat sur un GET c’est facile et cela fonctionne bien. En revanche la même chose pour un formulaire… je n’ai pas compris.

Si j’écris la documentation de cette manière:

<?php

/**
 * Class TicketStatusController
 * @package App\Controller
 * @RouteResource("TicketStatus", pluralize=false)
 * @SWG\Tag(name="Ticket status")
 */
class TicketStatusController extends AbstractFOSRestController
{
  // ...
  
  /**
     * Add status ticket
     *
     * @param Request $request
     * @return \Symfony\Component\Form\FormInterface
     *
     * @SWG\Parameter(
     *     name="ticket status",
     *     in="body",
     *     required=true,
     *     @Model(type=TicketStatus::class)
     * )
     * @SWG\Response(
     *     response=201,
     *     description="Add status ticket",
     *     @Model(type=TicketStatus::class)
     * )
     * @SWG\Response(response="400", description="Bad request")
     */
    public function postAction(Request $request) {
        return $this->crud->processForm($request, TicketStatusType::class, new TicketStatus());
    }
}

J’obtien le résultat suivant dans ma documentation:

C’est logique… cependant je ne m’attends pas à ce que la propriété id soit fournie, dans mon TicketStatusType je ne l’ai pas définit ainsi.
Si en lieu et place de TicketStatus::class (ligne 23) j’indique TicketStatusType::class pour indiquer qu’il faut se référer au définition du formulaire j’obtiens:

C’est pas mal… mais si c’est correcte par rapport au POST ça ne l’est pas pour le PUT ou le PATCH puisque les champs seront indiqué comme obligatoire alors qu’il n’en est rien pour le PATCH par exemple.

D’autant qu’en faisant cela, si j’ai pris la peine de documenter une propriété de mon entité à l’aide de @Property je ne retrouve pas cette documentation dans le formulaire

Bref, avez-vous une idée sur la façon de s’y prendre ?

Bien à vous
La source