fix #582 itemOperation Normalization/Denormalization in doc

[Simperfit]

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

I think i'm not bad on this but there is a part of this I don't know how to handle :
Since we are overriding on method, how do I tell the property-info / nelmio that we want this only for the PUT part ?

/**
 * @see http://schema.org/Thing
 *
 * 
 * @ApiResource(iri="http://schema.org/Thing", attributes={
 *     "normalization_context"={"groups"={"thing_default_output"}},
 *     "denormalization_context"={"groups"={"thing_default_input"}}
 * }, itemOperations={
 *     "get"={"method"="GET", "normalization_context"={"groups"={"thing_default_out_get"}}, "denormalization_context"={"groups"={"thing_default_in_get"}}},
 *     "put"={"method"="PUT", "normalization_context"={"groups"={"thing_default_out_put"}}, "denormalization_context"={"groups"={"thing_default_in_put"}}},
 *     }
 * )
 */

Right now I only get the overrided part in the doc. It is the intended behaviour ?

Which means I lost the ones in the attributes.

@dunglas What do I miss ?

[teohhanhui]

@Simperfit This is not the right way to fix it. Please use ResourceMetadata::getItemOperationAttribute.

And the same fix needs to be applied to the collection operations too (because normalization and denormalization also take place).

[Simperfit]

@teohhanhui This does not change the behaviour, or does it, just to reuse already implemented method ?

Yes thanks I forgot about the collection.

[Simperfit]

@teohhanhui I've changed.
$options is good and contain all what it needs :
if we take the exemple on the PR :

'serializer_groups' =>
'thing_default_output',
'thing_default_input',
'thing_default_out_get',
'thing_default_out_put',

But it does not show the parameters linked to thing_default_out_put / thing_default_out_get

[Simperfit]

ping @AlexandreHagen could you please test this and tell me if it's correct the issue ?

ping @teohhanhui @dunglas @theofidry this is RFR.

[AlexandreHagen]

Hi @Simperfit

Unfortunately, it is not seem to work as expected:

Annotations setup:

* @ApiResource(
 *     attributes={
 *          "normalization_context"={"groups"={"user","user_read"}},
 *          "denormalization_context"={"groups"={"user","user_write"}},
 *     },
 *     collectionOperations={
 *          "get"={"method"="GET"},
 *          "post"={"method"="POST"},
 *     },
 *     itemOperations={
 *          "get"={"method"="GET"},
 *          "delete"={"method"="DELETE"},
 *          "put"={
 *              "method"="PUT",
 *              "normalization_context"={"groups"={"user_read_put"}},
 *              "denormalization_context"={"groups"={"put"}},
 *          }
 *     },
 * ) 
...
 /**
     * @var string Username of the user.
     *
     * @Groups({"user_read", "user_write", "user_read_put"})
     * @Assert\NotBlank()
     */
    protected $username;

    /**
     * @var string Email of the user.
     *
     * @Groups({"user_read", "user_write"})
     * @Assert\Email(message="The email '{{ value }}' is not a valid email.", checkMX=true, checkHost=true)
     */
    protected $email;

    /**
     * @var string Firstname of the user.
     *
     * @Groups({"user_read", "user_write", "user_read_put", "user_write_put"})
     *
     * @ORM\Column(name="firstname", type="string", length=255)
     * @Assert\NotBlank
     */
    protected $firstname;
...

And i get:

For POST:

For PUT:

[Simperfit]

@teohhanhui @dunglas @vincentchalamon I need some help in here ;)

I can't get it working, either I get the itemCollection & operationCollection, either the resource groups for one entity. I think it is directly related to nelmio and this has to be checked in nelmio.

I don't think I can do things in ApiPlatform\Core\Bridge\NelmioApiDoc\Extractor\AnnotationsProvider\ApiPlatformProvider class.

Is there another class related to this ?

edit: yep the provider helped me.

[Simperfit]

ping @AlexandreHagen I think this time is the good time ;). Thank you for ur time.
It does work properly for me.

[AlexandreHagen]

You are close !

But something still not working.
When we set specific definition of (de)normalisation, property name is displayed as Input and Output.

Example:

 * @ApiResource(
 *     attributes={
 *          "normalization_context"={"groups"={"user_read"}},
 *          "denormalization_context"={"groups"={"user_write"}},
 *     },
 *     collectionOperations={
 *          "get"={"method"="GET"},
 *          "post"={"method"="POST"},
 *          "confirmation"={
 *              "route_name"="user_confirmation",
 *          },
 *          "post_invitation"={
 *              "method"="POST",
 *              "path"="/users/{invitation_code}",
 *              "normalization_context"={"groups"={"user_read_invitation"}},
 *              "denormalization_context"={"groups"={"user_write_invitation"}}
 *          },
 *     },
 * )
...
  /**
     * @var string Username of the user.
     *
     * @Groups({"user_read", "user_write", "user_write_invitation"})
     * @Assert\NotBlank()
     */
    protected $username;

    /**
     * @var string Email of the user.
     *
     * @Groups({"user_read", "user_write", "user_write_invitation"})
     * @Assert\NotBlank()
     * @Assert\Email(message="The email '{{ value }}' is not a valid email.", checkMX=true, checkHost=true)
     */
    protected $email;

    /**
     * @var string Firstname of the user.
     *
     * @Groups({"user_read", "user_write", "user_write_invitation"})
     *
     * @ORM\Column(name="firstname", type="string", length=255)
     * @Assert\NotBlank()
     */
    protected $firstname;

    /**
     * @var string Lastname of the user.
     *
     * @Groups({"user_read", "user_write", "user_write_invitation"})
     * @ORM\Column(name="lastname", type="string", length=255)
     * @Assert\NotBlank()
     */
    protected $lastname;

    /**
     * @var boolean Shows that the user is enabled (email confrimation)
     *
     * @Groups({"user_read", "user_read_invitation"})
     */
    protected $enabled;

    /**
     * @var string Password of the user.
     *
     * @Groups({"user_write", "user_write_invitation"})
     * @Assert\Regex(
     *  pattern="/(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9]).{7,}/",
     *  message="Le mot de passe doit contenir au moins 7 caractères alphanumériques dont une majuscule, une minuscule et un chiffre."
     * )
     */
    protected $plainPassword;
...

Doc:

As expected plainPassword is only in Input and enabled is only in Output .
But username, email etc... should be only in Output. But they are in both.
It seems that user_read is still considered !

I hope it's help and thanks for you work !

[teohhanhui]

What is this for? Please just use ResourceMetadata::getItemOperationAttribute and ResourceMetadata::getCollectionOperationAttribute properly. There's already a fallback mechanism in place (4th / last argument).

[Simperfit]

This is what i'm doing inside of it. Look at the parse method, I added the operationName because I needed to. In in order to have the parse method not full of code, I made this method.

[teohhanhui]

@Simperfit If you just use the fallback mechanism, it'd avoid a lot of unnecessary code.

This method is not needed in the first place.

/cc @dunglas

[dunglas]

@teohhanhui you're right, this method should be deleted.

[dunglas]

@Simperfit can you finish this PR? Can I help you in any way?

[dunglas]

IMO the problem is here, shoud should keep the if(isset())/else structure or both read and write groups are added.

[Simperfit]

@dunglas Thank you for the help.

@AlexandreHagen Is it ok for you ? I have been testing this and this I feel it ok. Thanks for the time & and the help

[AlexandreHagen]

I don't know why but I got that:

FatalThrowableError in ApiPlatformProvider.php line 39:
Type error: Argument 2 passed to ApiPlatform\Core\Bridge\NelmioApiDoc\Extractor\AnnotationsProvider\ApiPlatformProvider::__construct() must be an instance of ApiPlatform\Core\Documentation\ApiDocumentationBuilderInterface, instance of ApiPlatform\Core\Hydra\ApiDocumentationBuilder given, called in /var/www/opendecide_api_v2/app/cache/dev/appDevDebugProjectContainer.php on line 958

I'm trying to solve it

[AlexandreHagen]

Okey ! It's can be merged ! Thanks @Simperfit !

[dunglas]

Thanks for fixing this Hamza.