How to upload a file in swagger-php array

Question

I want to uplaod a file in swagger-php in the json requestBody How can upload with the help of swagger anonations

Trying from lot of hours but not luck how can send and file in application/json array Can you help if any information about this so then i will solve my problem i have not concept about this

when this code generate in the terminal also not have any error and not shown in the request body in the 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"),
*               ),
*           )
*       )
*     ),
* )
*/

I want to this type of swagger-ui body so that user can fill attribut and the resume add in base64 format

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

Answer 1

You may use @OA\Property(property="file", type="string", format="binary"), to define a file property:

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

Then you have to set a media type on your RequestBody using @OA\MediaType:

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

And finally on your @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")
 * )
 */

See also Swagger docs on File data type and File upload for more info.

Update: If you don't want separate declarations just merge them like this:

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

You may also want an approach with PHP classes

So you can define a model like that:

/**
 * @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
}

after you can define for example the body of a POST request as follows:

<?php

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

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

And lastly create the your Request in your documentation for example:

/**
 * @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:

If you want a request that have a file to the request body you way do:

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

And make your field in your PHP class:

/**
 * @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
}

You can see an example here: swagger-php/Examples/petstore.swagger.io/controllers/PetController.php