swagger tags not working

[rubenvdlinde]

I tried to implement swagger tags on the API resources (as to cluster my entities in the UI, large API's get confusing in the docs otherwhise) but the swagger_context dosn't seem to be working on @ApiResource just on @ApiProperty (as per docs btw so not really surprising). I'm a doing something wrong or is swagger_context simply not supported on @ApiResource?

 * @ApiResource(attributes={
 *     "normalization_context"={"groups"={"read"}},
 *     "denormalization_context"={"groups"={"write"}},
 *     "iri"="http://schema.org/Person",  
 *     "swagger_context"={
 *          "tag"={
 *              "name": "HRM",
 *              "description": "Human Resource Managment operations"
 *          }
 *     } 
 * })

[silverbackdan]

I know you can override documentation as described here: https://api-platform.com/docs/core/swagger/#swagger--open-api-support

But I'm not sure that defining this in the ApiResource annotation is supported, although it'd be a nice feature IMO.

[Simperfit]

You can set the swagger_context key in the ApiProperty annotation and you can do it per Operation, not directly like this.

And you can change the name like this : https://api-platform.com/docs/core/swagger/#using-the-swagger-context

Is it ok for you ? @rubenvdlinde

[Simperfit]

Closing as we got no feedbacks.

[rubenvdlinde]

Not really since this still deals with swagger on a property basis instead of a resource base, and one would like to set tags on a resource

[er1z]

Is using SwaggerDecorator insufficient?

[astronati]

@Simperfit The problem is still reproducible, it seems I'm not able to set a Swagger tag on an @ApiResource.

Could you re-open the issue?

[HellPat]

Yep, same problem on my side. I'm tryping to group a custom-operation (which is ApiResouce) to a different group in the docs using Tags https://swagger.io/docs/specification/grouping-operations-with-tags/.

I need to add the swagger_context to the ApiResource directly to do so.

[DaveData]

I was also not able to add tags with the ApiResource annotation. But, as already mentioned in this thread, you can do it with a SwaggerDecorator.

Add a decorator as described here: https://api-platform.com/docs/core/swagger/#overriding-the-openapi-specification then you can do something like this:

final class SwaggerDecorator implements NormalizerInterface
{

    // ...

    public function normalize($object, string $format = null, array $context = [])
    {
        $docs = $this->decorated->normalize($object, $format, $context);

        // ...

        $docs = $this->groupByPath('/auth/', 'Auth', $docs);
        $docs = $this->groupByPath('/enums/', 'Enums', $docs);

        return $docs;
    }

    private function groupByPath($pathContains, $tag, $docs)
    {
        foreach ($docs['paths'] as $path => $doc) {
            if (strpos($path, $pathContains) === false) {
                continue;
            }

            foreach ($doc as $operation => $params) {
                $docs['paths'][$path][$operation]['tags'] = [$tag];
            }
        }

        return $docs;
    }

}

[cyrilverloop]

If someone is looking for an API Platform 3.0 example :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\OpenApi\Model\Operation;

#[
    ApiResource( // Works also per operation.
        openapi: new Operation(
            tags: ['MyTag']
        )
)]
class MyResource
{

[COil]

If someone is looking for an API Platform 3.0 example :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\OpenApi\Model\Operation;

#[
    ApiResource( // Works also per operation.
        openapi: new Operation(
            tags: ['MyTag']
        )
)]
class MyResource
{

Also works with API Platform 2.7.