Symfony 属性

编辑此页

NelmioApiDocBundle 能够从 symfony 控制器属性自动创建文档。

MapQueryString

使用 Symfony MapQueryString 属性允许 NelmioApiDocBundle 从您的对象自动生成端点的查询参数文档。

修改生成的文档

修改生成的文档可以通过两种方式轻松完成： 自定义对象属性的文档 (#[OA\Property] 属性) 自定义查询参数的文档 (#[OA\Parameter] 属性)

自定义特定查询参数的文档可以通过将 #[OA\Parameter] 属性添加到您的控制器方法来完成。确保 in 属性设置为 'query' 并且 name 属性设置为您要自定义的对象属性名称。

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

MapQueryParameter

使用 Symfony MapQueryParameter 属性允许 NelmioApiDocBundle 自动生成端点的查询参数文档。

修改生成的文档

自定义查询参数的文档可以通过将 #[OA\Parameter] 属性添加到您的控制器方法来完成。确保 in 属性设置为 'query' 并且 name 属性设置为控制器方法参数的名称。

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

MapRequestPayload

使用 Symfony MapRequestPayload 属性允许 NelmioApiDocBundle 自动生成端点的请求体文档。

修改生成的文档

自定义请求体的文档可以通过将 #[OA\RequestBody] 属性添加到您的控制器方法来完成。

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

完整示例

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)
    {
        // ...
    }
}

自定义

假设您想要为路由参数添加、修改或删除一些文档。为此，您必须创建自己的描述器，该描述器实现 RouteArgumentDescriberInterface 接口。

注册您的路由参数描述器

在使用自定义描述器之前，您必须将其在路由参数描述器中注册为服务，并使用 nelmio_api_doc.route_argument_describer 标记它。实现 RouteArgumentDescriberInterface 接口的服务将由 NelmioApiDocBundle 自动检测和使用。

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

免责声明

请确保使用至少 php 8.1（属性支持）以使用此功能。

本作品，包括代码示例，根据 Creative Commons BY-SA 3.0 许可获得许可。
目录
    版本