Add Custom Operation to different Group in ApiPlatform docs

Question

I have a custom Operation CreatePerson which is dispatched via messenger.

/**
 * @ApiResource(
 *     messenger=true,
 *     output=false,
 *     shortName="person",
 *     collectionOperations={
 *         "post"
 *     },
 *     itemOperations={}
 * )
 *
 * @psalm-immutable
 */
final class CreatePerson

This works as expected with POST /api/people (people instead of person because ApiPlatform uses Inflection to pluralize the shortname on collectionOperations.

The API-Docs look like that:

I'd like to add a list of persons, too. So I created an other Api-Resource:

/**
 * @ApiResource(
 *     collectionOperations={
 *         "get"
 *     },
 *     itemOperations={}
 * )
 *
 * @psalm-immutable
 */
final class Person

The shortname of my customOperation ist person. This is also the group in the docs I want my list operation in.

Everything works as expected. Person and CreatePerson are two ApiResources. But now my docs look like that:

I want to group them both together in the API-Docs (because they belong together).

The reason why I use an extra CreatePerson-DTO here is because I use Api-Platform completely without doctrine. The DTO gets dispatched through messenger and creates a Person via Event-Sourcing. The Person-class is a readonly projection.

Answer 1

The solution for me was using openapi_context.

/**
 * @ApiResource(
 *     messenger=true,
 *     output=false,
 *     collectionOperations={
 *          "post"={
 *              "method"="POST",
 *              "path"="/people",
 *              "openapi_context"={
 *                  "tags"={
 *                      "Person"
 *                  },
 *             },
 *         },
 *     },
 *     itemOperations={},
 * )
 *
 * @psalm-immutable
 */
final class CreatePerson

And Person:

/**
 * @ApiResource(
 *     collectionOperations={
 *          "get"
 *     },
 *     itemOperations={},
 * )
 * @ORM\Entity(repositoryClass="App\Repository\PersonRepository")
 *
 * @psalm-immutable
 */
final class Person

(seen here: https://github.com/api-platform/docs/issues/143)

With the following result in the docs: