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

【问题标题】：How to specify to swagger-php that my parameter is going to be a file?如何向 swagger-php 指定我的参数将是一个文件？
【发布时间】：2022-09-29 16:12:40
【问题描述】：

我使用带有属性样式（不是注释）的最新 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),
            ]);
    }

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

我可能完全离开了，但请看这里github.com/zircote/swagger-php/issues/876
@GuidoFaecke 在浏览了这些链接之后，我找到了解决方案！感谢您的反馈。我将在这里发布解决方案。

标签： php symfony swagger

【解决方案1】：

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

<?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。

【讨论】：

【解决方案2】：

这个对我有用

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")
                ]
            )
        )],
    ),

【讨论】：