NelmioApiDocBundle v4.0.0-BETA1，未找到 $ref

Question

我有一个这样的 DTO：

# AppBundle\DTO

/**
 * @OA\Schema(
 *      schema="ProductDto",
 *      type="object",
 *      required={
 *          "foo",
 *          "bar",
 *          "baz",
 *      },
 * )
 */
class ProductDto
{
    /**
     * @OA\Property(description="foo bar baz")
     * @var string|null
     */
    private $foo;

    ...
 }

我试图在我的控制器中引用这个 DTO，但似乎这个文件没有被解析。

# AppBundle\Controller\Api\v1
class ProductController {

  ...

  /**
    * @OA\Post(
    *      @OA\RequestBody(
    *          required=true,
    *          content={
    *              @OA\MediaType(
    *                  mediaType="application/json",
    *                  @OA\Schema(
    *                      type="object",
    *                      ref="#/components/schemas/ProductDto",
    *                  ),
    *              ),
    *          }
    *      ),
    * )
    */
  public function create(Request $request): ApiResponse

  ...
}

这导致：

用户注意事项：在 /srv/vendor/doctrine/annotations/lib/Doctrine 中的 \Doctrine\Common\Annotations\DocParser->Annotation() 中找不到 @OA\Schema() 的 $ref "#/components/schemas/ProductDto" /Common/Annotations/DocParser.php 第 827 行

看来如果我将 DTO 放入 Controller 命名空间中，就会找到并解析该文件，但引用仍然不起作用。不过它可以与纯 swagger-php 包一起使用。

我正在使用当前的 Beta（v4.0.0、NelmioApiDocBundle），因为我想使用 OpenAPI 3。我需要以不同的方式引用它吗？这是包中的错误，还是我做错了？

Answer 1

NelmioApiDocBundle 使用 zircote/swagger-php 注释，但它不会像 zircote/swagger-php 那样解析它们。

这个想法是利用 symfony 已经提供的元数据来简化文档的编写。这些元数据包括路由的路径、验证注释、fosrest 注释以及暴露给 Symfony 序列化器（或 JMS 序列化器，具体取决于您使用的内容）的模型的属性。

为了做到这一点，这个包不会加载它找到的所有 swagger-php 注释，而是执行一些特定的加载，@Operation例如，它在控制器操作上加载注释（并且不需要路径）。这同样适用于模型，需要使用特殊注释在某处引用它们，@Model以便为其加载添加一些上下文。

您可以在捆绑包的文档中找到更多上下文：https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html#use-models。

在你的情况下，你应该使用ref=@Nelmio\ApiDocBundle\Annotation\Model(type=ProductDTO::class 而不是ref="#/components/schemas/ProductDto.