[API] add docs to show API Platform implementation.

[jrushlow]

This guide is incomplete and should not be used until after it is merged. Everything subject to change until then.

refs #128

Relates to symfony/maker-bundle#798

[jrushlow]

TODO - Do not return a 500 if the user could not be found.

[jrushlow]

Routes:

POST /reset-password-requests 
{
    "email": "[email protected]"
}

Responses:
202 - Request succeeds || User not found (We don't want to reveal who is a user and who is not)
422 - if email is not set, is empty, or otherwise malformed

PUT /reset-passwords/{token}

{
    "newPlaintextPassword": "some new password"
}

{token} = the token provided to the user via email

Responses:
200 - Token accepted, password changed.
404 - Invalid Token || User not Found || Any exception thrown by ResetPasswordHelper

[weaverryan]

It might be easier to split this into 2 DTO objects - something like RequestResetPasswordInput and ResetPasswordInput. Then you can configure the input on each, specific operation i think (instead of having the input= on the top-level.

Another option would be to create these 2 DTO's and make THEM each their own @ApiResource... each with 1 operation. I'm not sure if having ResetPasswordRequest as the @ApiResource is doing us any favors, as we never use it as the input or output. That would be my biggest potential feedback on this otherwise awesome effort. input and output DTO's are kind of an edge-case feature in API Platform... so if we can find a clean way to do this without them, that might ideal.