Custom Symfony Action with API Platform bundle

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