Allow an input and an output for a given resource class

[soyuka]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	may fix some issues
License	MIT
Doc PR	api-platform/docs#703

[meyerbaptiste]

You have to add these two new keys in the ApiResource annotation.

[dunglas]

Some minor comments, but awesome!

[ragboyjr]

@soyuka @dunglas Few things:

1. I don't see any changes to the Swagger Documentation Normalizer, so it's possible that the swagger docs could be out of sync with the actual api.
2. I implemented a similar feature here: https://github.com/krakphp/api-platform-extra#operation-resource-classes. The difference however is that mine is set per resource, and this is set on the class level. I'm not sure which one is better, but it may be a thing where both would valuable. Bringing this up for discussion though.

In my implementation, in order to keep the documentation in sync, I added a new attribute to schema_only which is used for defining resources that don't have any operations and are used just for being in the swagger definitions.

Let me know what you think.

[ragboyjr]

Oh, and most important thing... Thanks for all the hard work you too do for this project! I'm like 4 api platform projects in and I'm loving it more and more!

[dunglas]

Thanks Antoine!

[sroze]

Not bad 😉

[karser]

This looks great, but still not clear the transition between

!> The following isn't recommended anymore, please use Input/Output instead
/**
 * @ApiResource(
 *      collectionOperations={
 *          "post"={
 *              "path"="/users/forgot-password-request",
 *          },
 *      },
 *      itemOperations={},
 * )
 */
final class ForgotPasswordRequest

And

/**
 * @ApiResource(
 *   inputClass=Input::class,
 *   outputClass=Output::class,
 * )
 */
final class Data

Is input/output only resource level or it can be applied for operation as well?

Is it still possible to use Input/Data in the subscriber on POST_VALIDATE event or it works only in the data persister?

What would be the correct yaml syntax? This didn't work, at least wasn't relfected in swagger:

App\Dto\ForgotPasswordRequest:
    inputClass: 'App\Dto\ForgotPasswordRequest'
    outputClass: 'App\Dto\ForgotPasswordResponse'
    collectionOperations:
        post:
            path: '/users/forgot-password-request'
    itemOperations: {}

[ragboyjr]

@karser, from what I can tell, these can be applied at the resource level or at the operation level (which freaking rocks)

[ragboyjr]

It looks like we'll need to update the swagger documentation generator to take into account these changes as well.

[soyuka]

Is input/output only resource level or it can be applied for operation as well?

It should be available yes, if not lmk I'll fix it.

Is it still possible to use Input/Data in the subscriber on POST_VALIDATE event or it works only in the data persister?

In fact, the input class is mainly used to know how the (de)normalizer should work. As the validate event comes before the write (data persister) you should definitely be able to use the input data there.

What would be the correct yaml syntax? This didn't work, at least wasn't relfected in swagger:

I need to update the swagger documentation to reflect the changes. These are attributes first guess would be:

App\Dto\ForgotPasswordRequest:
    attributes:
        inputClass: 'App\Dto\ForgotPasswordRequest'
        outputClass: 'App\Dto\ForgotPasswordResponse'

Note that you can use either the input, the output or both.

[karser]

Thanks, I'll try it within today

[karser]

I tried added outputClass in attributes and it still works (at least api tests don't fail) but swagger part is still not displaying the outputClass.
I see, the swagger part is not implemented #2305
Now I realize that I can switch from setting response in subscriber to data persister and let api-platform serialize the result.

[lyrixx]

I totally missed this feature. And I really love this feature. I will be able to remove custom code \o/ Thanks.

Just a side note not related: You really need a blog (I'm not talking about https://api-platform.com/news/). Something like Symfony "Living on the Edge
" > "New in Symfony 4.3: Console Hyperlinks" https://symfony.com/blog/new-in-symfony-4-3-console-hyperlinks and another category about releases.

[dunglas]

@lyrixx I try to write a blog post for every releases with an explanation of new features like this one: https://dunglas.fr/category/programmation/php/api-platform/

This feature hasn't been released yet, it's why there are no blog posts about it yet.

However having a proper blog, or maybe a Planet, would be nice. We'll do it at some point.

[maks-rafalko]

I am curious, what is Planet? :)

[dunglas]

Basically a RSS feeds aggregator: https://en.wikipedia.org/wiki/Planet_(software)
2006, I feel old now 😅