Core: Swagger documentation of related entities isn't proper

[kate-kate]

Hello everyone.
I have a Job entity with related Campaign. According to https://api-platform.com/docs/core/serialization-groups-and-relations I configured them like this:

<?php

namespace AppBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * Job
 * @ApiResource(attributes={"normalization_context"={"groups"={"dashboard"}}})
 * @ORM\HasLifecycleCallbacks
 * @ORM\Table(name="job")
 * @ORM\Entity
 */
class Job
{
    /**
     * @var integer
     *
     * @ORM\Column(name="id", type="integer", nullable=false)
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="IDENTITY")
     */
    private $id;

    /**
     * @Groups({"dashboard"})
     * @ORM\Column(name="status", type="integer", nullable=false)
     */
    private $status;

    /**
     * @Groups({"dashboard"})
     * @ORM\Column(name="postcode", type="string", length=255, nullable=true)
     */
    private $postcode;

    /**
     * @Groups({"dashboard"})
     * @ORM\ManyToOne(targetEntity="Campaign")
     * @ORM\JoinColumns({
     *   @ORM\JoinColumn(name="campaign_id", referencedColumnName="id")
     * })
     */
    private $campaign;

    // ...
}

<?php
namespace AppBundle\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * Campaign
 * @ORM\HasLifecycleCallbacks
 * @ApiResource(attributes={"normalization_context"={"groups"={"dashboard"}}})
 * @ORM\Table(name="campaign")
 * @ORM\Entity
 */
class Campaign
{
    /**
     * @var integer
     *
     * @ORM\Column(name="id", type="integer", nullable=false)
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="IDENTITY")
     */
    private $id;

    /**
     * @var string
     * @ORM\Column(name="external_id", type="string", length=255, nullable=true)
     */
    private $externalId;

    /**
     * @var string
     * @Groups({"dashboard"})
     * @ORM\Column(name="name", type="string", length=255, nullable=false)
     */
    private $name; 

    // ...
}

And it works perfectly OK, when I get the response body, but the example value of response is quite strange.

Example value swagger shows to me

[
  {
    "status": 0,
    "postcode": "string",
    "campaign": {
      "status": 0,
      "postcode": "string",
      "campaign": {}
    }
  }
]

As you can see, there are job fields expected from campaign instead of its own

[jsamouh]

Hi @kate-kate ,

Generally, the same for me, I get several errors concerning "Example value" generation.

I recognize it's a hard (according to me) stuff to work on Swagger generation definition with API platform data ^^
I hope for the future, strong functionnal tests, with a maximum of cases (groups, relations, embedded...)

@Simperfit , what I see here might be the problem. It takes the definitionkey Jobs Entity instead of calling $this->resourceMetadataFactory->create($className)->getShortName(). (Campaign Entity)

But I suppose, if we change that, it will breaks another things ^^

[jonadoe]

Hi @kate-kate and @jordscream

I also struggled with this and created PR https://github.com/api-platform/core/pull/996 which fixes this issue. But to be absolutely sure it would be greate if @Simperfit could also check the PR to make sure it doesn't break PR #888

[kate-kate]

@jonadoe I've tested your changes locally, and they solved not only this issue, but also #988
Great job! Looking forward your changes will be merged to master