OpenAPI(Swagger3.0) ファイル送信APIを記述する

本記事で扱うこと

• ファイル送信API(POST)の記述方法(YAML形式)および関連するオブジェクトの説明

本記事の構成

1. ファイル送信APIの記述例
2. 記述例を参照しながら、記述の解説
3. openapi.yaml全体の記述例

1. ファイル送信APIの記述例

# ~~省略
requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          filename:
            type: string
          file:
            type: string
            format: binary
# 省略~~

2. 記述例を参照しながら、記述の解説

ファイル送信APIにとって、肝となる部分はcontentとtypeです。

まずPOST通信なので、parametersではなくrequestBodyを使用します。

次にcontentについて、通常であればapplication/jsonを定義することが多いと思いますが、ファイル送信APIではmultipart/form-dataを定義します。
このことにより、Swagger Viewerで確認するときにも、動作の確認を行いやすくなります。

最後にfileプロパティのtypeとformatがstringとbinaryになっています。
これはSwagger3.0に(2.0もそうなのですが)fileタイプが用意されていないため、このような記述になっています。
このことは、公式ドキュメントのこちらに記載されています

3. openapi.yaml全体の記述例

openapi: "3.0.2"
info:
  version: 1.0.0
  title: Qiita Demo File Upload API
  license:
    name: MIT
servers:
  - url: http://api-qiitayou.com/
paths:
  "/fileUpload":
    post:
      tags:
        - "File Upload API"
      summary: ファイルのアップロードを行います
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: string
                file:
                  type: string
                  format: binary
      responses:
        200:
          description: レスポンスは省略します