【Laravel】L5-Swaggerでファイルを含むリクエストボディを定義する

目的

L5-Swaggerは、LaravelのOpenAPI（Swagger）の仕様書を記述するためのライブラリです。
リクエストボディにファイルを含む場合のSwagger-PHPの記述方法を備忘録として残します。

実行環境

• Laravel 10
• OpenAPI 3.1.0

記述方法

下記の例のように@OA\MediaTypeを指定する必要があります。
参考: File Upload (Swagger)
ファイルの場合、プロパティのtypeはstring、formatはbinaryです。

    /**
     * @OA\Post(
     *     path="/api/image",
     *     summary="画像をアップロードする",
     *     @OA\RequestBody(
     *         @OA\MediaType(
     *             mediaType="multipart/form-data",
     *             @OA\Property(
     *                 property="image",
     *                 type="string",
     *                 format="binary"
     *             )
     *         )
     *     )
     * )
     */

これは、次のyamlの定義に相当します。

paths:
  /api/image:
    post:
      summary: 画像をアップロードする
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary

Swagger UIでも、ファイルのアップロードを検証することができます。