Custom Symfony Action with API Platform bundle - php

Question

I try to build an API with the Symfony bundle API-Platform.
Api resource offer automatic CRUD action with the HTTP verbs POST, GET, PUT, DELETE.
What I want is adding an endpoint to handle a custom POST action, with a custom payload/body, not depending on any resource.
Where I block it is to add this endpoint to the automatic API-Platform documentation.
When looking for this kind of issue on GitHub, I found that the API-Platform v2 should be able to do it.
See Issue #385 : Custom action + ApiDoc
It looks like some people find the way to use NelmioApiDoc #ApiDoc annotation.
See Issue #17 : Documentation for custom operation

Answer 1

Using the #ApiDoc annotation is a no go, support for NelmioApiDoc will be removed in API Platform 3 in favor of the builtin Swagger/Hydra support.
If you use a custom API Platform action, the action should automatically be documented in Swagger and Hydra docs.
Anyway, you can always customize the Swagger (and Hydra) docs to add custom endpoints or anything else: https://github.com/api-platform/docs/blob/master/core/swagger.md#override-swagger-documentation (this documentation will be available on the website soon).

Answer 2

You can document your own route with the #ApiResource() annotation:
/**
* #ORM\Entity
* #ApiResource(
* itemOperations={
* "get"={"method"="GET"},
* "put"={"method"="PUT"},
* "delete"={"method"="DELETE"},
* "send_reset_password_token"={
* "route_name"="user_send_reset_password_token",
* "swagger_context" = {
* "parameters" = {
* {
* "name" = "email",
* "in" = "path",
* "required" = "true",
* "type" = "string"
* }
* },
* "responses" = {
* "201" = {
* "description" = "email with reset token has been sent",
* "schema" = {
* "type" = "object",
* "required" = {
* "email"
* },
* "properties" = {
* "email" = {
* "type" = "string"
* },
* "fullname" = {
* "type" = "string"
* }
* }
* }
* },
* "400" = {
* "description" = "Invalid input"
* },
* "404" = {
* "description" = "resource not found"
* }
* },
* "summary" = "Send email with token to reset password",
* "consumes" = {
* "application/json",
* "text/html",
* },
* "produces" = {
* "application/json"
* }
* }
* }
* },
* attributes={
* "normalization_context"={"groups"={"user", "user-read"}},
* "denormalization_context"={"groups"={"user", "user-write"}}
* }
* )
*/
Source: https://github.com/api-platform/docs/issues/143#issuecomment-260221717

Answer 3

You can create custom post action like this.
Map resources configuration to yaml.
# config/packages/api_platform.yaml
api_platform:
enable_swagger_ui: false
mapping:
paths: ['%kernel.project_dir%/config/api_platform']
Create resources.yaml
# config/api_platform/resources.yaml
resources:
App\Entity\User:
itemOperations: []
collectionOperations:
post:
method: 'POST'
path: '/auth'
controller: App\Controller\AuthController
swagger_context:
summary: your desc
description: your desc
Then in App\Entity\User add public properties
class User {
public $login
public $password
}
It is all, now in swagger ui u will see method POST /api/auth with login and pass parameters.
In u controller override _invoke for execute your logic.
class AuthController {
public function __invoke()
{
return ['your custom answer'];
}
}

Answer 4

I ran into the same situation because I tried to put the POST method into itemOperations, although it can only reside in collectionOperations. In the latter in can successfully define my custom path.
/**
* #ApiResource(
* collectionOperations={
* "get"={
* "path"="/name_your_route",
* },
* "post"={
* "path"="/name_your_route",
* },
* },
* itemOperations={
* "get"={
* "path"="/name_your_route/group/{groupId}/user/{userId}",
* "requirements"={"groupId"="\d+", "userId"="\d+"},
* },
* "delete"={
* "path"="/name_your_route/group/{groupId}/user/{userId}",
* },
* "put"={
* "path"="/name_your_route/group/{groupId}/user/{userId}",
* }
* })
Hopefully helpful for others that stumble upon this question.
And here is the paragraph from the great documentation about it:
Collection operations act on a collection of resources. By default two
routes are implemented: POST and GET. Item operations act on an
individual resource. 3 default routes are defined GET, PUT and DELETE