Implement subresource metadata and annotation

[soyuka]

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

For now the @ApiSubresource only does the same thing as @ApiProperty(subresource=true). It'll be better with metadata and an annotation class if we want to add features to it in the future.

Related to #1188. ping @pierredup

[soyuka]

Should it be a PROPERTY annotation? I don't think we need it, and there is no value in adding metadata factories for subresources IMO. Lmk.

[dunglas]

I agree, @ApiSubresource() directly on the property is easier to type, to read and to understand.

[dunglas]

Should be @Target({"METHOD", "PROPERTY"})

[dunglas]

Nevermind, my bad.

Error

[teohhanhui]

I suggest we take this opportunity to make it:

/**
 * @ApiSubresource(operations=true)
 */
protected $children;

(open to better name)

[soyuka]

What does operations trigger?

[teohhanhui]

@ApiSubresource is for configuring a subresource, just like how @ApiProperty is for configuring a property. It also implies that the property is a subresource (what does this do?). The actual configuration is therefore whether to expose the operations (only GET, for now).

[teohhanhui]

On second thought, we should add operations when we actually support overriding the operations. 😆

[soyuka]

Okay but I suggest we expose operations without having a operations flag. It doesn't make sense to declare ApiSubresource if you don't want operations, does it?

[teohhanhui]

Okay, maybe we need to have a clear definition of what we call a subresource (for our purposes):

A "subresource" is a resource exposed under a path with parameters dependent on another resource.

[dunglas]

Ok for me when Travis will be green (see comment).

[dunglas]

Missing use statement (it should made Travis happy btw).

[soyuka]

last minute test \o/ fixed thx.

[meyerbaptiste]

You have to remove the return type here.

[teohhanhui]

I'm -1 for this. It duplicates information already available from the Type via PropertyMetadata.

[soyuka]

It does and in the end we'll have less function calls to retrieve the same information.

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

This will also ease the maintenance to have a SubresourceMetadata class if we need to support subresource related cases in the future no?

[dunglas]

Thanks @soyuka!

[ghost]

Hi!!
It's possible to do the paging with @ApiSubResource?

For example I have Objects that have many comments! and i would like recover the comments through the Object and paging the reponse!!

[soyuka]

Please open a new issue, and if it's a collection it should already be paginated.

[ghost]

@soyuka It's already implemted! It was that i didnt see it in the subResource url api_doc.
thanks