How to set Nelmio Doc with a custom JMS Serializer Handler

Question

In the generated NelmioApiBundle my relations are displayed as {} instead of 0.

I use a custom JMS Handler for Object Relations. (RelationHandler)

On my relations I specify a special Class as type in the given Model (ChildRelation). The handler then manages the conversion from Object to ID. This works great for JMS Serializer but not for the corresponding Nelmio API Doc

I have tried to mess with @SWG\Schema directly on ChildRelation but this did not work

In this example role is technically a UserRole Object which inherits from Concrete.

## serializer/Model.DataObject.User.yml
AppBundle\Model\DataObject\User:
    access_type: public_method
    properties:
        capabilities:
            groups: [detailed, data]
            type: array<string>
        role:
            groups: [detailed, list, data, create, update]
            type: AppBundle\Model\DataObject\ChildRelation

// RelationHandler Serializer:
final class RelationsHandler implements SubscribingHandlerInterface
{
 (...)
public function serializeConcreteToId(JsonSerializationVisitor $visitor, Concrete $concrete, array $type, SerializationContext $context
    ) {
        return $concrete->getId();
    }
}

I expect to get the same model as I get when calling the endpoint.

{
  "role": 271,
  "capabilities": []
}

But in swagger the response looks like this:

{
  "capabilities": [],
  "role": {}
}

Is there a nice way to do this?

Answer 1

The solution to this problem would be to simply introduce your own ObjectDescriber which listens to the specific Object Type. The class could look something like this:

use EXSyst\Component\Swagger\Schema;
use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareInterface;
use Nelmio\ApiDocBundle\Describer\ModelRegistryAwareTrait;
use Nelmio\ApiDocBundle\Model\Model;
use Nelmio\ApiDocBundle\ModelDescriber\ModelDescriberInterface;

class ChildRelationDescriber implements ModelDescriberInterface, ModelRegistryAwareInterface
{
    use ModelRegistryAwareTrait;

    public function supports(Model $model): bool
    {
        return "AppBundle\Model\DataObject\ChildRelation" === $model->getType()->getClassName();
    }

    public function describe(Model $model, Schema $schema)
    {
        $schema->setType('integer');
    }
}

register it with your application

child_relation_describer:
    class: AppBundle\ChildRelationDescriber
    tags:
        - {name: nelmio_api_doc.model_describer, priority: 1000}

and voila!