[Swagger] [Question] [Potential PR] nested object that are not ressources

[jcotineauCoffreo]

Hello everyone, i am opening this issue as a question and an hypothetic PR.

I've faced an issue while using api-platform, quite the same as #285 which is closed now.
to fix it i changed the behavior of the DocumentNormalizer and the SerializerPropertyMetadataFactory so that nested object that are not resource are still displayed in the swagger document; but i am not sure if this changes in behavior still match the philosophy of api-platform.

So here come the example :
I have a TimeRecord, WHICH IS a resource
And two other classes NbHours and Extras that ARE NOT resources

/**
 * Class TimeRecord.
 * @ApiResource
 */
class TimeRecord
{
    /**
     * @var string
     */
    public $id;

    /**
     * @var string
     */
    public $date;

    /**
     * @var string
     */
    public $comment;

    /**
     * @var \App\Entity\NbHours
     */
    public $nbHours;

    /**
     * @var \App\Entity\Extras
     */
    public $extras;

    /**
     * TimeRecord constructor.
     */
    public function __construct()
    {
    }
}

/**
 * Class NbHours.
 */
class NbHours
{
    /**
     * @var int
     */
    public $day = 0;

    /**
     * @var int
     */
    public $night = 0;

    /**
     * NbHours constructor.
     */
    public function __construct()
    {
    }
}

With the default configuration my TimeRecord model with be displayed like this :

With the modifications I've done it will display this :

Same example with the json returned from operations
Before the modifications :

After the modifications :

I've seen this issue many times and it seemed great to me to have a complete model of an object based on the serialization groups and property types even for non-resource object.

I am a trainee and i have not a lot of knowledge, neither in api-platform nor swagger nor symfony, but i'll be very happy to contribute to this project.

Please excuse me for my poor english,
I am looking forward to hearing from you soon on this subject.

[dunglas]

It looks legit to me. Your contribution will be very welcome!

[Simperfit]

Same for me, I think this could a be a great improvement!

[teohhanhui]

Legit. Is everything else working fine other than the OpenAPI (Swagger) docs?

[jcotineauCoffreo]

@teohhanhui this is what i am investigating now, all tests passes except one.
I found why, so i am trying to figure out the best way to fix it.

[Gingonic]

@jcotineauCoffreo Any news on this? This would be a nice PR when using auto-generated Swagger Clients. Right now mine crash an burn because of this.
Could you may be publish your PR so we can have a look at your code so far?

[jcotineauCoffreo]

I'll try to ask my boss to push the PR asap .
But for now the code isn't really clean, i have not worked a lot on it, but it should put everyone who wants on a good way to solve this.

[teohhanhui]

Currently, it's only possible to document API resource classes and input/output classes. That's not right. The user should be able to document any class.

Suggestions on how we could achieve that are welcome.

[soyuka]

We already talked about this with @dunglas, there is a need to add some resource metadata according to input/output configuration or DTO properties so that these classes can also be documented :).