Openapi on ポンコツ地方エンジニアの技術ブログ

WebAPI で multipart/form-data を使う

Thu, 02 Jun 2022 00:00:00 +0900

AI を使った画像解析システムなどでは、画像をリクエストで投げて推論結果をレスポンスでもらう、というのをよくやるかと思います。

そういった API で、最初は画像を Base64 に変換して JSON で渡していたのですが、エンコード/デコードの処理時間があるため、バイナリでデータを送りたいと考えました。
また、１度のリクエストで複数枚の画像を送る必要があるのと、画像の対する付加情報（カメラのIDや画像の取得日時など）も一緒に渡す必要があるということで、multipart/form-data を使って送ってみることにしました。

multipart/form-data についての詳細は割愛しますが、バウンダリ文字列で区切って複数のデータを送信するやつで、HTML の form 文とかで使われるやつです。

今まで WebAPI では json と yaml しか扱ったことありませんでしたが、調べた感じ、WebAPI でも multipart/form-data を使ってテキストとバイナリを一緒に送るというのはよくある手法っぽいです。

リクエスト内容

例として、POST で以下のような内容を送ります。

ヘッダー（抜粋）

Content-Type multipart/form-data; boundary=cc874efaa4e6a1e85c14280c96a7b237

サンプルコードを後に載せていますが、バウンダリ文字列は自動生成でリクエスト毎に異なります。
基本的に意識しなくても大丈夫でした。

ペイロード

テキストについては一つずつ text/plain で送ろうかとも思いましたが、今後データが増えた時にサーバー側の処理が面倒かなと思い、JSON にまとめることにしました。
画像データ以外は JSON でまとめて送り、画像データはバイナリで送ります。
これをカメラ台数分送ります。カメラ毎に JSON と画像をマッピングする必要がありますが、試行錯誤した結果、name にカメラを識別するためのIDを設定することにしました。つまり、name の値を見てどのカメラの JSON データ、画像データかを識別する想定です。
後述するサンプルコードで試した結果、ペイロードは以下のような形になりました。

--cc874efaa4e6a1e85c14280c96a7b237
Content-Disposition: form-data; name="カメラのID"

{
 "camera_id": "1",
 "datetime": "2021-08-05T17:07:01.388437",
}
--cc874efaa4e6a1e85c14280c96a7b237
Content-Disposition: form-data; name="カメラのID"; filename="ファイル名"
Content-Type: image/jpeg

<ここに画像のバイナリデータが入る>
--cc874efaa4e6a1e85c14280c96a7b237--

複数カメラ分のデータを送信した場合、並びは以下ようになりました。

１台目のカメラの JSON データ
２台目のカメラの JSON データ
１台目のカメラの画像データ
２台目のカメラの画像データ

name でどのカメラかを判別できるので、基本的にこの並びは意識しなくても大丈夫でした。

サンプルコード

Python での実装例です。

クライアント側

上記のリクエストを requests モジュールを使って送信するサンプルです。

import requests
import json
from datetime import datetime

if __name__ == '__main__':
 data = {}
 files = {}
 # 複数カメラを想定して送信
 for camera_id in ['hoge', 'piyo']: # 各カメラのID
 # 適当なテキストデータ
 json_data = {
 'camera_id': camera_id,
 'datetime': datetime.now().isoformat()
 }
 # 適当な画像ファイルを読み込む
 image = None
 filename = 'send_image.jpg'
 with open(filename, 'rb') as f:
 image = f.read()

 # 送信
 # data,files は dict 型でなければならないので、カメラIDをキーとして渡すことにした。このキーが name に設定される
 data[camera_id] = json.dumps(json_data), # dict -> str への変換
 # filename や Content-Type を指定して送りたい場合
 files[camera_id] = (filename, image, 'image/jpeg')
 # 画像のみで送りたい場合。filename は name と同じになり、Content-Type は付与されなかった
 #files[camera_id] = image
 res = requests.post(f'http://localhost:8000', files=files, data=data)
 print(res)

サーバー側

上記のリクエストを Flask で受信するサンプルです。

import json
from flask import Flask, request

if __name__ == '__main__':
 app = Flask(__name__)

 @app.route('/', methods=['POST'])
 def index():
 print(request.headers)
 #print(request.get_data()) # 生データ
 # JSON データの受け取り
 for key, value in request.form.items():
 json_data = json.loads(value) # str から dict への変換
 print(f'json, key={key}:, value={json_data}, type={type(json_data)}')
 # 画像データの受け取り
 for key, value in request.files.items():
 print(f'image, key={key}, type={type(value)}') # FileStorage 型
 #print(value.headers)
 # ファイルに保存して確認
 with open(f'{key}.jpg', 'wb') as f:
 f.write(value.read())
 # ファイルの保存だけなら以下でも可
 #value.save(f'{key}.jpg')
 return {}, 200

 app.run(port=8000, debug=True)

OpenAPI で multipart/form-data を記述する

OpenAPI で API の仕様書を作成しているのですが、multipart/form-data は以下のように記述するようです。
ただ、上述したような name をカメラのIDとするような記述はできないようです。
ここでは json_data image という値で記述しています。

また、Content-Type を記述したい場合は encoding を使うそうですが、Swagger で試しに送信しても付与されていませんでした。あと、Redoc ではリクエストボディの内容が表示されませんでした。
``multipart/form-data` 自体に対応していないのかもしれません。

/endpoint:
 post:
 summary: サンプル
 description: 説明
 requestBody:
 content:
 multipart/form-data:
 schema:
 type: object
 required:
 - json_data
 - image
 properties:
 data:
 type: object
 required:
 - camera_id
 - datetime
 description: 画像以外のデータ(JSON)
 properties:
 camera_id:
 type: string
 description: カメラの識別子
 example: 'hoge'
 datetime:
 type: string
 format: date-time
 description: 画像の取得日時(ISO8601)
 example: '2021-08-05T17:07:01.388437'
 image:
 type: string
 format: binary
 description: 画像データ(バイナリ)
 encoding:
 image:
 contentType: image/jpeg;

参考 URL

OpenAPI + Swagger + Redoc + GitLab Pages で API ドキュメントを管理する

Tue, 24 May 2022 00:00:00 +0900

APIドキュメントを簡単に作成・閲覧できるようにしたいと思い、OpenAPI で作成、Swagger および Redoc で表示、GitLab Pages で公開までを行いました。

概要

OpenAPI で yaml を作成
GitLab CI/CD により自動で Swagger および Redoc でビルドし、GitLab Pages に公開
ローカル環境用に Swagger および Redoc を Docker で動かす

ディレクトリ構造

今回試しに作成したファイル一式は以下となります。詳細は後述します。

$ tree -a
.
├── .gitlab-ci.yml
├── README.md
├── docker-compose.yml
├── openapi
│ └── openapi.yaml
└── public
 └── index.html

OpenAPI の yaml を作成

Open API Specification (OAS) は REST API の仕様を記述するフォーマットです。記述方法についてはググったらたくさん出てくるので割愛します。

例えば、以下のような yaml を作成します。

openapi: 3.0.0
info:
 version: 1.0.0
 title: OpenAPI Sample
paths:
 /users:
 get:
 summary: Get Users
 responses:
 '200':
 description: OK

ローカル環境の作成

ひとまず GitLab は置いておき、まずはローカル環境で Swagger および Redoc が動くようにしてみます。
３つのサービスを動かしたかったので、docker-compose 使いました。
作成した docker-compose.yml は以下です。

version: '3'
services:
 # エディター
 swagger-editor:
 image: swaggerapi/swagger-editor
 ports:
 - "8081:8080"
 # ビューワー（Swagger-UI 版）
 swagger-ui:
 image: swaggerapi/swagger-ui
 volumes:
 - ./openapi:/usr/share/nginx/html/openapi
 environment:
 API_URL: ./openapi/openapi.yaml # Swagger UIの画面を開いたときに初期値として表示するファイル
 ports:
 - '8082:8080'
 # ビューワー（Redoc 版）
 redoc:
 image: redocly/redoc
 volumes:
 - ./openapi:/usr/share/nginx/html/openapi
 environment:
 SPEC_URL: ./openapi/openapi.yaml # Redocの画面を開いたときに初期値として表示するファイル
 PORT: 8080 # nginx port(default:80)
 ports:
 - '8083:8080'

特に難しいところはないかと思います。
docker-compose up で動かしたあと、ブラウザでアクセスすればOKです。

http://localhost:8081 で Swagger Editor にアクセスして編集が行えます。
http://localhost:8082 で Swagger UI での表示を確認できます。
http://localhost:8083 で Redoc での表示を確認できます。

ただ、Swagger Editor は別にいらなかったかもしれません。
私の場合、結局 VSCode で yaml を編集し、ブラウザの表示を更新して確認、ってやってます。

閲覧に関しては Swagger より Redoc のほうが個人的に見やすいですね。

GitLab Pages で公開する

ローカルでの環境は以上で整ったので、次は GitLab に push したら自動ビルドを行って GitLab Pages に公開するように設定します。
GitLab Pages や GitLab CI/CD については割愛します。

Swagger + GitLab Pages については以下のページが参考になりました。

https://lab.astamuse.co.jp/entry/2019/11/13/114500

ただ、今回 swagger-ui-dist のバージョンを上げたので、sed コマンドで修正するファイルを index.html から swagger-initializer.js に変更する必要がありました。
これについては以下のページが参考になりました。

https://qiita.com/hidao/items/d13e7dda3da02d37dd45

Redoc + GitLab Pages については以下のページが参考になりました。

https://medium.com/hoursofoperation/auto-generate-swagger-docs-to-gitlab-pages-ca040230df3a

以上の２つを組み合わせ、最終的に作成した .gitlab-ci.yml は以下です。
Swagger と Redoc のそれぞれで閲覧できるようにディレクトリを分けてみました。
プロキシ環境下でなければプロキシ関係の設定は不要です。

image: node:18-alpine

variables:
 # プロキシサーバー
 PROXY: 'http://example:8080'
 # ドキュメントのあるディレクトリ
 DOCS_FOLDER: "swagger"
 # ドキュメントファイル
 SPEC_TO_DISPLAY: "openapi.yaml"
 # デプロイ先
 DEPLOY_SWAGGER: "public/swagger"
 DEPLOY_REDOC: "public/redoc"

cache:
 paths:
 - ./node_modules

pages:
 stage: deploy
 before_script:
 # プロキシ環境下での下準備
 - npm -g config set proxy $PROXY
 - npm -g config set https-proxy $PROXY
 - npm -g config set registry http://registry.npmjs.org/
 - npm config set strict-ssl false
 # Swagger UI
 - npm install swagger-ui-dist@4.11.1
 # Redoc
 - npm install -g redoc-cli@0.13.14
 script:
 - mkdir -p $DEPLOY_SWAGGER
 - mkdir -p $DEPLOY_REDOC
 # Swagger UI
 - cp -rp node_modules/swagger-ui-dist/* $DEPLOY_SWAGGER
 - cp -rp $DOCS_FOLDER/* $DEPLOY_SWAGGER
 - sed -i "s#https://petstore\.swagger\.io/v2/swagger\.json#$SPEC_TO_DISPLAY#g" $DEPLOY_SWAGGER/swagger-initializer.js
 # Redoc
 - redoc-cli build -o $DEPLOY_REDOC/index.html $DOCS_FOLDER/$SPEC_TO_DISPLAY
 artifacts:
 paths:
 - public
 only:
 - main

ちなみに、Swagger の yaml ファイルは GitLab 上で Swagger でプレビュー表示されるので、外部に公開する必要がなければこれで十分かもしれません。

https://blog.kyanny.me/entry/2020/08/06/012807