时间戳

首页 > 解决方案 > NelmioApiDocBundle v4.0.0-BETA1，未找到 $ref

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

问题描述

我有这样的 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

  ...
}

这导致：

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

似乎如果我将我的 DTO 放入 Controller 命名空间，正在找到并解析该文件，但引用仍然不起作用。不过，它适用于纯 swagger-php 包。

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

标签： openapiswagger-phpnelmioapidocbundle

解决方案

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.

推荐阅读