Symfony attributes

NelmioApiDocBundle has the ability to automatically create documentation from symfony controller attributes.

MapQueryString

Using the Symfony MapQueryString attribute allows NelmioApiDocBundle to automatically generate your query parameter documentation for your endpoint from your object.

6.3

The MapQueryString attribute was introduced in Symfony 6.3.

Modify generated documentation

Modifying the generated documentation can easily by done in two ways, by: Customizing the documentation of an object's property (#[OA\Property] attribute) Customizing the documentation of a query parameter (#[OA\Parameter] attribute)

Customizing the documentation of a specific query parameter can be done by adding the #[OA\Parameter] attribute to your controller method. Make sure that the in property is set to 'query' and that the name property is set to the object's property name which you want to customize.

        1
2
3
4
5
        #[OA\Parameter(
    name: 'id',
    description: 'Some additional parameter description',
    in: 'query',
)]
    

MapQueryParameter

Using the Symfony MapQueryParameter attribute allows NelmioApiDocBundle to automatically generate your query parameter documentation for your endpoint.

6.3

The MapQueryParameter attribute was introduced in Symfony 6.3.

Modify generated documentation

Customizing the documentation of the query parameter can be done by adding the #[OA\Parameter] attribute to your controller method. Make sure that the in property is set to 'query' and that the name property is set to the name of the controller method parameter.

        1
2
3
4
5
        #[OA\Parameter(
    name: 'id',
    description: 'Some additional parameter description',
    in: 'query',
)]
    

MapRequestPayload

Using the Symfony MapRequestPayload attribute allows NelmioApiDocBundle to automatically generate your request body documentation for your endpoint.

6.3

The MapRequestPayload attribute was introduced in Symfony 6.3.

Modify generated documentation

Customizing the documentation of the request body can be done by adding the #[OA\RequestBody] attribute to your controller method.

        1
2
3
        #[OA\RequestBody(
    groups: ["create"],
)
    

Complete example

        1
2
3
4
        class UserQuery
{
    public int $userId;
}
    

        1
2
3
4
5
6
7
8
9
        use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Validator\Constraints as Assert;

class UserDto
{
    #[Groups(["default", "create", "update"])]
    #[Assert\NotBlank(groups: ["default", "create"])]
    public string $username;
}
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
        namespace AppBundle\Controller;

use AppBundle\UserDTO;
use AppBundle\UserQuery;
use OpenApi\Attributes as OA;
use Symfony\Component\Routing\Annotation\Route;

class UserController
{
    /**
     * Find user with MapQueryString.
     */
    #[Route('/api/users', methods: ['GET'])]
    #[OA\Parameter(
        name: 'userId',
        description: 'Id of the user to find',
        in: 'query',
    )]
    public function findUser(#[MapQueryString] UserQuery $userQuery)
    {
        // ...
    }

    /**
     * Find user with MapQueryParameter.
     */
    #[Route('/api/users/v2', methods: ['GET'])]
    #[OA\Parameter(
        name: 'userId',
        description: 'Id of the user to find',
        in: 'query',
    )]
    public function findUserV2(#[MapQueryParameter] int $userId)
    {
        // ...
    }

    /**
     * Create a new user.
     */
    #[Route('/api/users', methods: ['POST'])]
    #[OA\RequestBody(
        groups: ['create'],
    )]
    public function createUser(#[MapRequestPayload] UserDTO $user)
    {
        // ...
    }
}
    

Customization

Imagine you want to add, modify, or remove some documentation for a route argument. For that you will have to create your own describer which implements the RouteArgumentDescriberInterface interface.

Register your route argument describer

Before you can use your custom describer you must register it in your route argument describer as a service and tag it with nelmio_api_doc.route_argument_describer. Services implementing the RouteArgumentDescriberInterface interface are automatically detected and used by NelmioApiDocBundle.

        1
2
3
4
5
        # config/services.yaml
services:
    App\Describer\CustomRouteArgumentDescriber:
        tags:
            - { name: nelmio_api_doc.route_argument_describer }
    

        1
2
3
4
        <!-- config/services.xml -->
<service id="App\Describer\CustomRouteArgumentDescriber">
    <tag name="nelmio_api_doc.route_argument_describer"/>
</service>
    

        1
2
3
4
5
6
7
8
9
        // config/services.php
use App\Describer\CustomRouteArgumentDescriber;

return function (ContainerConfigurator $container) {
    $container->services()
        ->set(CustomRouteArgumentDescriber::class)
        ->tag('nelmio_api_doc.route_argument_describer')
    ;
};
    

Disclaimer

Make sure to use at least php 8.1 (attribute support) to make use of this functionality.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version