Add Subresource to swagger docs

[pierredup]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	N/A
License	MIT
Doc PR	N/A

Display SubResources in the swagger docs

[soyuka]

Hmm this is a good idea. I didn't wanted to introduce a new Metadata class when I worked on subresources but this will give more power to subresource declarations (ping @teohhanhui ^^).

WDYT about going a bit further, so that PropertyMetadataFactory will create the SubResourceMetadata when it's declared as such? This is what the outcome may be in the code below:

$propertyMetadata = $this->propertyMetadataFactory->create($parentResourceClass, $property);
if ($propertyMetadata->hasSubresource()) {
        $subResourceMetadata = $propertyMetadata->getSubresource(); // this is an instance of SubResourceMetadata
}

With something like this we can avoid repeating the following code (for example also in ApiLoader):

$isCollection = $propertyMetadata->getType()->isCollection();
$resourceClass = $isCollection ? $propertyMetadata->getType()->getCollectionValueType()->getClassName() : $propertyMetadata->getType()->getClassName();

ping @api-platform/core-team

IMO we need to agree on this change first because it may involve many changes ^^. Anyway, if we introduce this new metadata class, it'd be a shame not to use it everywhere we can :).

[teohhanhui]

I don't think it's worth it to introduce yet another metadata class.

In fact, I'd argue for the removal of PropertyMetadata::$subresource property. Just use an attribute.

[dunglas]

Can you use a guard clause to make the code easier to read?

if (!$propertyMetadata->hasSubresource()) {
    continue;
}

[pierredup]

Closing in favor of #1225