如何上传swagger-php数组中的文件

Question

我想在json requestBody中上传一个swagger-php文件，怎样才能在swagger anonations的帮助下上传？

尝试了几个小时，但没有运气，如何在应用程序/json数组中发送和文件，如果有任何关于这方面的信息，你能帮我吗?那么我会解决我的问题，我没有这个概念

当此代码在终端中生成时也没有任何错误，并且没有显示在swagger ui中的请求正文中

/**
* @OA\Post(
*      path="/products/save",
*      tags={"Product"},
*      summary="Post bulk products",
*      description="Return bulk products",
*      @OA\RequestBody(
*       required=true,
*       description="Bulk products Body",
*       @OA\JsonContent(
*           @OA\Property(
*               property="products",
*               @OA\Items(
*                  @OA\Property(property="first_name", type="string"),
*                  @OA\Property(property="last_name", type="string"),
*                  @OA\Property(property="email", type="string"),
*                  @OA\Property(property="phone", type="string"),
*                  @OA\Property(property="resume", type="string", format="base64"),
*               ),
*           )
*       )
*     ),
* )
*/

我想要这种夸张的ui主体，以便用户可以填写属性和简历添加在base64格式

{
  "products": [
    {
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "phone": "string",
      "resume": "string" ==> here i will send base64 format of resume file
    }
  ]
}
``

Answer 1

您可以使用@OA\Property(property="file", type="string", format="binary"),来定义文件属性：

/**
 * @OA\Schema(
 *   schema="ProductRequest",
 *   required={"products"},
 *   @OA\Property(
 *       property="products",
 *       type="array",
 *       @OA\Items(
 *           @OA\Property(property="first_name", type="string"),
 *           @OA\Property(property="last_name", type="string"),
 *           @OA\Property(property="email", type="string"),
 *           @OA\Property(property="phone", type="string"),
 *           @OA\Property(property="resume", type="string", format="binary"),
 *       ),
 *    )
 * )
 */

然后，您必须使用@OA\MediaType在RequestBody上设置媒体类型

/**
 * @OA\RequestBody(
 *   request="Product",
 *   required=true,
 *   description="Bulk products Body",
 *   @OA\MediaType(
 *     mediaType="multipart/form-data",
 *     @OA\Schema(ref="#/components/schemas/ProductRequest")
 *   )
 * )
 */

最后在你的@OA\Post上

/**
 * @OA\Post(
 *   path="/products/save",
 *   tags={"Product"},
 *   summary="Post bulk products",
 *   description="Return bulk products",
 *   @OA\RequestBody(ref="#/components/requestBodies/Product"),
 *   @OA\Response(response=200, ref="#/components/responses/Product")
 * )
 */

有关更多信息，请参阅File data type和File upload上的Swagger文档。

更新:如果你不想要单独的声明，就像这样合并它们：

/**
 * @OA\Post(
 *   path="/products/save",
 *   tags={"Product"},
 *   summary="Post bulk products",
 *   description="Return bulk products",
 *   @OA\RequestBody(
 *     required=true,
 *     description="Bulk products Body",
 *     @OA\MediaType(
 *       mediaType="multipart/form-data",
 *       @OA\Schema(
 *         @OA\Property(
 *           property="products",
 *           type="array",
 *           @OA\Items(
 *             @OA\Property(property="first_name", type="string"),
 *             @OA\Property(property="last_name", type="string"),
 *             @OA\Property(property="email", type="string"),
 *             @OA\Property(property="phone", type="string"),
 *             @OA\Property(property="resume", type="string", format="binary"),
 *           )
 *         )
 *       )
 *     )
 *   )
 * )
 */

Answer 2

您可能还需要一种PHP类的方法

所以你可以这样定义一个模型：

/**
 * @OA\Schema(
 *     schema="User",
 *     required={"first_name", "last_name" // and so on}
 *  )
 */
class User 
{
    /**
     * @OA\Property(type="string")
     */
    public $first_name;

     /**
     * @OA\Property(type="string")
     */
    public $last_name;

    // add your other fields bellow
}

例如，您可以按如下方式定义POST请求的正文：

<?php

/**
 * @OA\Schema(
 *     schema="CreateUsers",
 *     required={"users"}
 *  )
 */
class CreateUsers
{

    /**
     * @var array
     * @OA\Property(ref="#/components/schemas/User")
     */
    public $users;
}

最后，在您的文档中创建您的请求，例如：

/**
 * @OA\Post(
 *      path="YOUR ROUTE URL",
 *      operationId="createUsers",
 *      tags={"Users"},
 *      @OA\RequestBody(
 *         required=true,
 *         @OA\MediaType(
 *             mediaType="application/json",
 *             @OA\Schema(ref="#/components/schemas/CreateUsers")
 *         )
 *     ),
 *      summary="Create a collection of users",
 *      description="Create a collection of users"
 *    )
 **/

EDIT 1:

如果你想在请求正文中包含一个文件，你可以这样做：

/**
 * @OA\Post(
 *      path="YOUR ROUTE URL",
 *      operationId="createUsers",
 *      tags={"Users"},
 *      @OA\RequestBody(
 *         required=true,
 *         @OA\MediaType(
 *             mediaType="multipart/form-data", // here we need to change from "application/json" to "multipart/form-data" in order to make our file visible
 *             @OA\Schema(ref="#/components/schemas/CreateUsers")
 *         )
 *     ),
 *      summary="Create a collection of users",
 *      description="Create a collection of users"
 *    )
 **/

并在PHP类中创建字段：

/**
 * @OA\Schema(
 *     schema="User",
 *     required={"first_name", "last_name", "file" // and so on}
 *  )
 */
class User 
{
    /**
     * @OA\Property(type="string")
     */
    public $first_name;

     /**
     * @OA\Property(type="string")
     */
    public $last_name;

     /**
     * @OA\Property(description="file to upload", type="string", format="file")
     */
    public $file;

    // add your other fields bellow
}

您可以在此处看到一个示例：