swagger-php - 是否需要 nelmio_api_doc.yaml 中的模式部分？

Question

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

在用户 Controller 中，我有以下注释:

     *     @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

在用户 Controller 中，我还定义了 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

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

感谢任何见解。

Answer 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))
     *        )
     *     )
     */