如何指定swagger-php我的参数将是一个文件？

Question

我使用最新的带有属性样式的swagger-php https://github.com/zircote/swagger-php (而不是注释)。我希望指定我的字段将是一个file。但我不知道该怎么做。我的控制器中有以下代码：

class FileController extends AbstractController
{
    #[OA\Parameter(parameter: 'file', name: 'file')]
    #[Route('/api/upload-file', name: 'app_upload_file', methods: ['post'])]
    public function uploadFile(ImageDto $imageDto, ConstraintViolationListInterface $errors): Response
    {
        return $this->json(
            [
                'success' => $errors === null,
                'errors' => $errors,
            ]
        );
    }
}

ImageDto是：

class ImageDto implements RequestObjectInterface
{
    #[Assert\NotBlank]
    public UploadedFile $file;

    public function getFile(): UploadedFile
    {
        return $this->file;
    }
}

我只需要在这里说明

我想要一个文件字段，而不是文本字段。

要使用DTO，我使用nelexa/request-dto-bundle包。但在这种情况下并不重要。问题是，我不知道如何指定我的参数将是文件。至少对我来说，源代码的可读性不太强。我给你举个例子

#[Property(...)]构造函数源代码。看一看这个：

 /**
     * @param array<string,Examples>    $examples
     * @param array<string,string>|null $x
     * @param Attachable[]|null         $attachables
     */
    public function __construct(
        ?string $parameter = null,
        ?string $name = null,
        ?string $description = null,
        ?string $in = null,
        ?bool $required = null,
        string|object|null $ref = null,
        ?Schema $schema = null,
        ?array $examples = null,
        ?string $style = null,
        ?bool $explode = null,
        // annotation
        ?array $x = null,
        ?array $attachables = null
    ) {
        parent::__construct([
                'parameter' => $parameter ?? Generator::UNDEFINED,
                'name' => $name ?? Generator::UNDEFINED,
                'description' => $description ?? Generator::UNDEFINED,
                'in' => Generator::isDefault($this->in) ? $in : $this->in,
                'required' => !Generator::isDefault($this->required) ? $this->required : ($required ?? Generator::UNDEFINED),
                'ref' => $ref ?? Generator::UNDEFINED,
                'style' => $style ?? Generator::UNDEFINED,
                'explode' => $explode ?? Generator::UNDEFINED,
                'x' => $x ?? Generator::UNDEFINED,
                'value' => $this->combine($schema, $examples, $attachables),
            ]);
    }

我不知道我应该使用什么杠杆来指定我希望这个字段是一个文件。

Answer 1

对我来说很管用

OA\RequestBody(
        content: [new OA\MediaType(mediaType: "multipart/form-data",
            schema: new OA\Schema(
                properties: [
                    new OA\Property(property: "upload", type: "file", format: "binary"),
                    new OA\Property(property: "num_chunks", type: "integer")
                ]
            )
        )],
    ),

Answer 2

在互联网上的旧代码示例之间走了几分钟之后，我终于得到了这样的结果：

<?php

namespace App\Controller;

use App\Dto\Files\ImageDto;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Validator\ConstraintViolationListInterface;
use OpenApi\Attributes as OA;

class FileController extends AbstractController
{
    #[OA\RequestBody(content: [new OA\MediaType(mediaType: 'multipart/form-data')])]
    #[OA\Parameter(parameter: 'file', name: 'file', schema: new OA\Schema(type: 'file') )]
    #[Route('/api/upload-file', name: 'app_upload_file', methods: ['post'])]
    public function uploadFile(ImageDto $imageDto, ConstraintViolationListInterface $errors): Response
    {
        return $this->json(
            [
                'success' => $errors === null,
                'errors' => $errors,
            ]
        );
    }
}

因此，我所需要的只是将schema: new OA\Schema(type: 'file')添加到#[OA\Parameter]属性中。

#[OA\RequestBody(content: [new OA\MediaType(mediaType: 'multipart/form-data')])] --我不确定这是否有任何效果，但它补充说：

​

​

好吧，就这样吧。

我还发布了控制器的整个类。我希望你注意到这句话：

use OpenApi\Attributes as OA;

我之所以这样做，是因为所有的例子都与这个OA一起使用，而没有一个特例，OA是什么，OA源在哪里。我对乞讨感到有点困惑。现在我知道OA是use OpenApi\Attributes as OA。