是否需要 nelmio_api_doc.yaml 中的架构部分？

Posted 2023-02-16

【中文标题】是否需要 nelmio_api_doc.yaml 中的架构部分？

【英文标题】：Is the schemas section in the nelmio_api_doc.yaml required?

【发布时间】：2020-10-11 14:10:49

【问题描述】：

我一直在使用 Swagger-php 设置 Nelmio API Doc Bundle。一切都按预期工作，我似乎无法弄清楚/理解的唯一一件事就是架构。

在用户控制器中，我有以下注释：

     *     @OA\RequestBody(
     *         description="Updated user object",
     *         required=true,
     *       @OA\MediaType(
     *           mediaType="multipart/form-data",
     *           @OA\Schema(ref="#/components/schemas/User")
     *        )
     *     )

在我的Entity/User 类中，我将架构定义如下：

/**
 * User
 *
 * @OA\Schema(schema="User")
 *
 * @ORM\Table(schema="app", name="users")
 * @ORM\Entity
 */
class User implements UserInterface

在用户控制器中，我还定义了use App\Entity\User;。

在我看来，这足以找到架构，但它不起作用，否则我不会在这里发布:)

我能够使其工作的唯一方法是运行 vendor/bin/openapi --format yaml src 并将架构输出复制/粘贴到 nelmio_api_doc.yaml 文件中。这是我复制/粘贴的架构部分：

        User:
          properties:
            first_name:
              type: string
            middle_name:
              type: string
            last_name:
              type: string
            initials:
              type: string
            username:
              type: string
            password:
              type: string
            status:
              type: integer
            email:
              type: string
            id:
              type: integer
            customer_id:
              type: integer
            locked:
              type: boolean
          type: object

所以我的问题是，这是解决问题的方法还是应该自动创建架构部分？

感谢您提供任何见解。

【参考方案1】：

NelmioApiDocBundle 不会加载所有文件来获取与 swagger-php 相反的注释，要加载架构，您应该使用@Model 注释，请参阅https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html#use-models。

在你的情况下，这将给出以下内容：

use Nelmio\ApiDocBundle\Annotation\Model;

     /**
     *     @OA\RequestBody(
     *         description="Updated user object",
     *         required=true,
     *       @OA\MediaType(
     *           mediaType="multipart/form-data",
     *           @OA\Schema(ref=@Model(type=User::class))
     *        )
     *     )
     */