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

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

class FileController extends AbstractController
{
    #[OAParameter(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
{
    #[AssertNotBlank]
    public UploadedFile $file;

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

我只需要在此处指定 enter image description here 我想要一个文件字段,而不是文本字段。

要使用 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),
            ]);
    }

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

stack overflow How to specify to swagger-php that my parameter is going to be a file?
原文答案

答案:

作者头像

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

<?php

namespace AppController;

use AppDtoFilesImageDto;
use SymfonyBundleFrameworkBundleControllerAbstractController;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentRoutingAnnotationRoute;
use SymfonyComponentValidatorConstraintViolationListInterface;
use OpenApiAttributes as OA;

class FileController extends AbstractController
{
    #[OARequestBody(content: [new OAMediaType(mediaType: 'multipart/form-data')])]
    #[OAParameter(parameter: 'file', name: 'file', schema: new OASchema(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 OASchema(type: 'file') 添加到我的 #[OAParameter] 属性中。

#[OARequestBody(content: [new OAMediaType(mediaType: 'multipart/form-data')])] 我不确定这有什么效果,但它添加了这个:

enter image description here

好吧,顺其自然。

我还发布了控制器的整个类。我希望你注意这一行:

use OpenApiAttributes as OA;

我已经完成了,因为所有示例都与此 OA 一起使用,并且没有一个电话是什么 OA 以及 OA 来源在哪里。一开始我有点迷茫。现在我知道 OA 是 use OpenApiAttributes as OA

作者头像

这个对我有用

OARequestBody(
        content: [new OAMediaType(mediaType: "multipart/form-data",
            schema: new OASchema(
                properties: [
                    new OAProperty(property: "upload", type: "file", format: "binary"),
                    new OAProperty(property: "num_chunks", type: "integer")
                ]
            )
        )],
    ),