API Platform: Change description of an endpoint

Question

I have created a custom endpoint using API Platform. Here is the annotation I have used:

/**
 * We only want the POST option for now.
 *
 * @ApiResource(
 *      itemOperations={},
 *      collectionOperations={"post"={
 *           "method"="POST",
 *           "controller"=PairingController::class,
 *           "path"="/devices/pairing",
 *           "defaults"={"_api_receive"=false}
 *     }},
 * )
 *
 *
 */
class Pairing
{
...

The controller I am calling executes some custom logic. I am happy with how things are working so far. But the documentation generated by API Platform is now inaccurate. It says:

/devices/pairing Creates a Pairing resource.

... which is no longer true, since my controller does not generate a pairing. (It calls out to a different API instead, asking that API to do some stuff.)

So here's my question: How do I change my annotation to allow me to write a custom piece of documentation for this endpoint?

Answer 1

You can use the swagger_context key to change any Swagger field, including description (the one you are looking for): https://api-platform.com/docs/core/swagger/#changing-operations-in-the-swagger-documentation