Laravelのl5-swaggerで、OpenAPI記法でmultipart/form-dataを表示する

はじめに

Laravelのl5-swaggerでAPIドキュメント兼API動作確認を行う際に、multipart/form-data形式でのswaggerを作成する方法。

TL; DR;

RequestBody の MediaType で mediaType="multipart/form-data"を指定する。
Schema の Property で項目を列挙する

記載方法

/**
 *
 * @OA\Post(
 *      path="/sample",
 *      operationId="multipart sample",
 *      @OA\RequestBody(
 *          @OA\MediaType(
 *              mediaType="multipart/form-data",// <-ここでマルチパートを指定する
 *              @OA\Schema(
 *                  type="object",// <-object形式にして複数の値を送信
 *                  @OA\Property(// <-送信項目の単位
 *                      property="item_1",// <-送信のキー名(formのname)
 *                      type="integer",
 *                      format="int32",
 *                      description="multipartの数値データとして送信する",//<-説明をつけられる
 *                  ),
 *                  @OA\Property(
 *                      property="image_file",
 *                      type="string",
 *                      format="binary",//<-バイナリデータも送信できる
 *                      description="画像などのバイナリも送信可能",
 *                  ),
 *              ),
 *          )
 *      ),
 *  )
 */

作成例

/**
 * APIコントローラの説明
 *
 * Class SampleController
 * @package App\Http\Controllers
 */
class SampleApiController extends Controller
{


    /**
     *
     * @OA\Post(
     *      path="/sample",
     *      operationId="Sample API",
     *      tags={"User"},
     *      summary="multipart/form-dataのサンプル",
     *      description="l5-swaggerで、OpenAPI記法でmultipart/form-dataを表示する",
     *      @OA\RequestBody(
     *          @OA\MediaType(
     *              mediaType="multipart/form-data",
     *              @OA\Schema(
     *                  type="object",
     *                  @OA\Property(
     *                      property="item_1",
     *                      type="integer",
     *                      format="int32",
     *                      description="multipartで数値データを送信",
     *                  ),
     *                  @OA\Property(
     *                      property="image_file",
     *                      type="string",
     *                      format="binary",
     *                      description="画像などのバイナリも送信可能",
     *                  ),
     *              ),
     *          )
     *      ),
     *      @OA\Response(
     *          response=200,
     *          description="正常な処理",
     *          @OA\JsonContent(
     *              type="object",
     *              @OA\Property(
     *                  property="property_1",
     *                  type="string",
     *                  description="返り値1(テキスト)",
     *              ),
     *              @OA\Property(
     *                  property="property_2",
     *                  type="integer",
     *                  description="返り値2(数値)",
     *              ),
     *          )
     *      ),
     *      @OA\Response(
     *          response=400,
     *          description="requsetデータに問題がある",
     *          @OA\JsonContent(
     *              type="object",
     *              @OA\Property(
     *                  property="error message",
     *                  type="object",
     *              ),
     *          )
     *      ),
     *      @OA\Response(response=500, description="Internal Server Error"),
     *      @OA\Response(response=404, description="Resource Not Found"),
     *  )
     *
     *
     * functionのコメント上に記載すると "swagger"の表示がバグるので、この位置に記載する
     * 
     * @param Request $request 入力データの説明
     * @return array|StreamInterface|JsonResponse 正常な返り値　or エラー結果
     */
    public function hogeFunction(Request $request)
    {
        // 処理
    }

}

以上です。