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

  ...
}

这导致：

User Notice: $ref "#/components/schemas/ProductDto" not found for @OA\Schema() in \Doctrine\Common\Annotations\DocParser->Annotation() in /srv/vendor/doctrine/annotations/lib/Doctrine/Common/Annotations/DocParser.php on line 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~~。

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

NelmioApiDocBundle v4.0.0-BETA1, $ref not found

swagger-php

nelmioapidocbundle

openapi