How to create custom endpoint in API Platform and add it to the documentation?

Question

I want to create not mapped with entity endpoint like /api/v1/me that returns information (User object) about currently authenticated user and add it to my documentation. In the plans I also want to add endpoints like /api/v1/account/recover and /api/v1/account/verify-email.

I have an action:

namespace AppBundle\Action\Me;

use AppBundle\Entity\User;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;

class MeView
{

    /**
     * @var TokenStorageInterface
     */
    private $tokenStorage;

    public function __construct(TokenStorageInterface $tokenStorage)
    {
        $this->tokenStorage = $tokenStorage;
    }

    /**
     * @Security("is_authenticated()")
     *
     * @Route(
     *     name="me_view",
     *     path="/me",
     *     methods={"GET"}
     * )
     *
     * @return User
     */
    public function __invoke()
    {
        return $this->tokenStorage->getToken()->getUser();
    }
}

But when I try to access it, it returns an exception:

The controller must return a response (Object(AppBundle\Entity\User) given). (500 Internal Server Error)

Same action, but mapped with entity, works well:

namespace AppBundle\Action\City;

use AppBundle\Entity\City;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
use Symfony\Component\Routing\Annotation\Route;

class CityView
{

    /**
     * @Security("is_authenticated()")
     *
     * @Route(
     *     name="city_view",
     *     path="/cities/{id}",
     *     methods={"GET"},
     *     defaults={"_api_resource_class"=City::class, "_api_item_operation_name"="view"}
     * )
     *
     * @param City $city
     * @return City
     */
    public function __invoke(City $city)
    {
        return $city;
    }
}

What should I do to make my custom action work and how to add it to auto-generated Swagger documentation?

Answer 1

Controller:

class MyUserController extends  Controller
{
    public function fn_me()
    {
        return $this->getUser();
    }
}

Entity:

 * @ApiResource(
 *  collectionOperations={
 *      "get","post",
 *      "collName_api_me"={"route_name"="api_me"}
 *  }
 * )
 */
class User implements UserInterface, \Serializable

routes.yaml

api_me:
    path: '/api/me'
    methods: ['GET']
    defaults:
        _controller: '\App\Controller\MyUserController::fn_me'
        _api_resource_class: 'App\Entity\User'
        _api_collection_operation_name: 'collName_api_me'