OpenAPI Generatorで踏んだバグたち
背景
現在所属しているチームでOpenAPI Specification 2.0(Swagger2.0)で記述されたAPI仕様書が放置されていた。
これをOpenAPI Generatorを利用してTypeScript向けのAPIクライアントのコードを自動生成したかった。(利用しようとしたOpenAPI Generatorのバージョンは4.0.3)
(OpenAPI Specification 3.0 にマイグレーション済み。)
踏んだ罠たちの書き殴り
OpenAPI Specification2.0から3.0にマイグレーション完了した!ので、コード自動生成してみるかー
components.requestBodies を定義すると壊れたコードが生成される
The following schema has undefined (null) baseType. It could be due to form parameter defined in OpenAPI v2 spec with incorrect consumes. A correct 'consumes' for form parameters should be 'application/x-www-form-urlencoded' or 'multipart/form-data'
とエラーが吐かれ、リクエストボディの中身が `UNKNOWN_BASE_TYPE` になってる
components: requestBodys: HogeRequestBody: ...
みたいにcomponents.requestBodiesを直接指定するのがアカンらしく
components: schema: Hoge: ...
components.schemasにスキーマを抽出してやって妥協するしかなさそう
oneOfを使うと壊れたコードが生成される
こういうやつ
hogeIndex: oneOf: - type: integer - type: string enum: - 0 - 1 - 2 - user
この辺 github.com
諦めてこうした
hogeIndex: type: string enum: - 0 - 1 - 2 - user
allOf を使っても壊れるという噂 oneOf と allOf は当面避けれるなら避けたほうが良さそう(OpenAPI Generatorが直ることを祈ろう)
application/x-www-form-urlencoded で requestBody に Collection を指定するとぶっ壊れる
ちゃんと名前空間が指定されてなくて、未定義変数を参照してるってなって壊れてるやつ
マジかよ...
application/x-www-form-urlencoded で パラメータのシリアライズがそんなにうまくいかない
パラメータのシリアライズとはこの辺の話 github.com
↑requestBodyでパラメータが配列のときhoge=fuga&hoge=piyo
みたいな指定できない。
強制的にcollectionFormatが "csv" hoge=fuga,piyo
みたいなカンマ区切りになる。
そんでもってrequestBodyではPHP特有の hoge[fuga]=piyo
がまだ考慮されてなさそう(そんなAPIのインタフェースをやめたほうがいい)
具体的にどういうことかというと
requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: hoge: type: array items: type: string encoding: hoge: style: form explode: true
としたとき、
先述したcollectionFormatがcsv固定になってしまってるので
isCollectionFormatMultiが立たないから
https://github.com/OpenAPITools/openapi-generator/blob/v4.0.3/modules/openapi-generator/src/main/resources/typescript-fetch/apis.mustache#L158-L162
そして問題の
application/x-www-form-urlencoded で requestBody に Collection を指定するとぶっ壊れる
に入る
以上。詰み。
github.com query parameterは対応しているのは見た
そんなネストしたオブジェクトをリクエストボディで送りたいならJSONを使えという話である
〆
とりあえず、壊れてないコードを生成することができるまでになった。
OpenAPI Generatorバグバグだけど、乗り越えられるとやっぱコードの自動生成サイコーという気持ちになります。