4

我想在 json requestBody 的 swagger-php 中上传一个文件 如何在 swagger anonations 的帮助下上传

尝试了很多时间，但运气不佳，如何在 application/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"),
*               ),
*           )
*       )
*     ),
* )
*/

我想要这种类型的 swagger-ui 正文，以便用户可以填写属性并以 base64 格式添加简历

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

2 回答 2

7

您可以使用@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"),
 *       ),
 *    )
 * )
 */

然后，您必须在RequestBodyusing上设置媒体类型@OA\MediaType：

/**
 * @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")
 * )
 */

另请参阅有关文件数据类型和文件上传的 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"),
 *           )
 *         )
 *       )
 *     )
 *   )
 * )
 */
于 2020-07-13T09:12:50.853 回答
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"
 *    )
 **/

编辑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
}

你可以在这里看到一个例子：swagger-php/Examples/petstore.swagger.io/controllers/PetController.php

于 2020-07-13T09:19:30.090 回答