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
    }
  ]
}
``

You need to provide significantly more detail for anyone to be able to help you. — Kurt Friars, Jul 13 '20 at 09:11

Hafez Divandari · Answer 1 · 2020-07-19T13:01:34.720

9

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

edited Jul 19 '20 at 13:01

answered Jul 13 '20 at 09:12

Hafez Divandari

8,381
4
46
63

Thank @Hafez Divandari for replying me one more question how can upload a file in the body when i upload a file then not show my code is **@OA\Property(property="resume", type="file",format="file")** but not work can you help for this issue – Spiral Jul 17 '20 at 10:26
Bro can you define the **ref** I'm new in swagger i can't understand that how can define the ref with model can you define plz Bro i want to upload a file in the multipart/form-data in application/json body – Spiral Jul 17 '20 at 18:21
@Spiral It is not necessary to use ref, I updated my answer. – Hafez Divandari Jul 17 '20 at 18:57
@hafezDivandarithe file part not showing in the application/json body. – Spiral Jul 18 '20 at 07:27
@hafezDivandarithe Bro i want to upload a file in array body Can you check this **Link** [link](https://stackoverflow.com/questions/62954088/how-can-send-multipart-form-data-file-in-application-json-in-swagger-php) for more define – Spiral Jul 18 '20 at 07:28
@hafezDivandarithe updated my question plz check this – Spiral Jul 18 '20 at 07:34
@Spiral compare your code to mine, your syntax is wrong, I added the full request to my answer. you don't have jsonContent anymore, use `mediaType` instead. – Hafez Divandari Jul 18 '20 at 20:19
bro when use your updated code then when generate docs then in swagger-ui i have not array of products and not seen the file in the array. Brother i want to upload a file in application/json array so that every array have its own file i want upload bulk products and in an array will have its own file. your code not working properly can you understant. when use your code then have only input field in swagger-ui not an array – Spiral Jul 19 '20 at 08:20
@Spiral the code is correct, but Swagger UI has limit on displaying complex arrays' items. here is the generated doc for products as array: https://api.npoint.io/98e0a0996b31bf18cfb9 that is what you want. for testing purpose you can delete the array part and see that the code works for a single object: https://api.npoint.io/273f7d27da864b6374bd – Hafez Divandari Jul 19 '20 at 13:08
@Spiral On the other hand, you can not use json when uploading a binary file! – Hafez Divandari Jul 19 '20 at 13:09
Ok Bro @hafezDivandari Thanks for helping me i understanding sorry for that i want not upload file i want to send resume in base64 format but my issue is that i have a bulk array which working fine but one issue which i facing i want to send a base64 format in array which not sending in the array updated my question – Spiral Jul 19 '20 at 13:57
@Spiral just add `type="array",` after `property="products",` – Hafez Divandari Jul 19 '20 at 14:00
supporse your code is work fine but how can send array of data in one file with the make array in swagger-ui how can understand the user that how can make array of data – Spiral Jul 19 '20 at 14:03
bro @hafezDivandari can you see my updated question above i want to this type of array in swagger-ui – Spiral Jul 19 '20 at 14:19
Bro one more thing your updated code is working fine how can use this or how can make a array in add items first_name, last_name, phone, email, resume for multiple array – Spiral Jul 19 '20 at 14:22
when use your code and put array in items then show **Error** The products must be an array. – Spiral Jul 19 '20 at 14:29
Bro base64 error not comming with your code but **the prodcuts must be an array** this error comming plz can you tell me what will be the model/example to pass array in swagger-ui – Spiral Jul 19 '20 at 15:34

loic.lopez · Answer 2 · 2020-07-17T11:48:35.210

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

Thank @loic.lopez for replying me one more question how can upload a file in the json body when i upload a file then not show my code is @OA\Property(property="file", type="file",format="file") but not work can you help for this issue — Spiral, Jul 17 '20 at 10:35
@Spiral make an edit to your question to precise more clearly what is not working — loic.lopez, Jul 17 '20 at 10:44
You may see: https://github.com/zircote/swagger-php/issues/666#issuecomment-501921007 @Spiral — loic.lopez, Jul 17 '20 at 10:46
Ok Bro i can define so that you can understand my problem i want to upload a file in the array you can see my code ` * @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="file", type="file",format="file") * ), ` this code not working for upload a file in the array — Spiral, Jul 17 '20 at 11:05
Thanks @loic.lopez for helping i sending a link in this comment you can i want to like this [link](https://stackoverflow.com/questions/62954088/how-can-send-multipart-form-date-in-application-json-in-swagger-php) i want to upload file in application/json mean that multipart/form-date in json body — Spiral, Jul 17 '20 at 12:40
@loicLopez upldate my question plz check this i want to upload a file in json body because i have a file upload in an array — Spiral, Jul 18 '20 at 07:47

How to upload a file in swagger-php array

2 Answers2