API平台文档问题：错误地将路由参数视为必填ID

Question

我遇到了 API 平台的问题，它似乎将路由参数视为必需的 idBadge，即使我的路由配置中没有这样指定。设置如下：

我有一个 Symfony 控制器方法，可以通过其矩阵（特定标识符）检索徽章：

/**
 * @Route("/badges_search/{matricule}", name="app_search_badge_matricule", methods={"GET"})
 */
public function searchBadgeByMatricule(SerializerInterface $serializer, BadgeRepository $badgeRepository, string $matricule): Response
{
    $badge = $badgeRepository->findOneBy(['matricule' => $matricule]);
    if (!$badge) {
        return new Response(null, 404);
    }

    $badgeSerialize = $serializer->serialize($badge, 'json');
    return new Response($badgeSerialize, 200, ['content-type' => 'application/json']);
}

但是，当我查看生成的 API 文档时，它错误地将 idBadge 列为必需参数，即使 idBadge 不是我的路由参数的一部分，也没有在我的注释中的任何位置指定。

这是我的

Badge

课程

<?php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use App\Repository\BadgeRepository;
use Doctrine\ORM\Mapping as ORM;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;

#[ORM\Entity(repositoryClass: BadgeRepository::class)]
#[ORM\Table(name : "badge")]
#[ApiResource(
    operations: [
        new Get(),
        new GetCollection(),
        new Get(name: "recherche_badge_matricule",
        routeName: "app_search_badge_matricule",
        openapiContext: [
            "parameters" => [
                [
                    "name" => "matricule",
                    "in" => "path",
                    "required" => true,
                    "type" => "string",
                    "description" => "Matricule du badge"
                ]
                ],
                "responses" => [
                    "200" => [
                        "description" => "Badge trouvé",
                        "content" => [
                            "application/json" => [
                                "schema" => [
                                    "type" => "object",
                                    "properties" => [
                                        "idBadge" => [
                                            "type" => "integer"
                                        ],
                                        "matricule" => [
                                            "type" => "integer"
                                        ],
                                        "numeroBadge" => [
                                            "type" => "integer"
                                        ],
                                        "soldeBadge" => [
                                            "type" => "number"
                                        ]
                                    ]
                                ]
                            ]
                        ]
                    ],
                    "404" => [
                        "description" => "Badge non trouvé"
                    ]
                ],
                "summary" => "Recherche d'un badge par matricule",
                "description" => "Recherche d'un badge par matricule"
                
        ])
    ]
)]
class Badge
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(name: "idBadge")]
    private ?int $idBadge = null;

    #[ORM\Column(name: "matricule")]
    private ?int $matricule = null;

    #[ORM\Column(name: "numeroBadge")]
    private ?int $numeroBadge = null;

    #[ORM\Column(name: "soldeBadge")]
    private ?float $soldeBadge = null;

我从昨天开始就遇到这个问题，但文档继续将 idBadge 显示为必需参数。

我尝试了几种注释，但似乎无法弄清楚问题出在哪里。我已多次检查我的实体和控制器注释，但文档仍然错误地将 idBadge 列为必需参数。我不确定问题是否出在类定义或控制器配置中。尽管清除了缓存并检查了是否有任何错误配置，但我找不到问题的根源。作为 API 平台的新手，这可能是我忽略的注释中的一个简单错误。任何有关如何正确设置文档以将矩阵反映为路径参数而不会将其错误地识别为 idBadge 的指导将不胜感激。

任何人都可以建议如何向 API 平台澄清 matricule 不是 idBadge 并确保其正确记录为路径参数而不将其与其他实体标识符混淆吗？

Answer 1

我已经确定了问题的根源。我的 API 平台注释中的

Get()

方法似乎需要在主键或唯一字段上进行搜索，但在我的 Badge 实体中并未配置“matricule”。为了解决这个问题，我只是在

Get()

类的注释中将

GetCollection()

替换为

Badge

。这有助于 API 平台理解“matricule”是一个不同于主标识符 (idBadge) 的路径参数。