TypeScript & Rails プロジェクトに OpenAPI (swagger) の導入を検討する。
現状 / 課題
- APIが増えてきたのでドキュメント化したい
- またTypeScript を導入したので、api レスポンス Type を生成したい
- Type を手動で書くなら ドキュメントの schema から生成したら楽そう
- バックエンドは Rspec をしているので自動で schema 生成 ⇨ schema から type 生成すればいいのでは?
- いい感じの型が生成されない。自動生成 schema の限界がある?
- そもそももっと良い開発フロー & いい感じのフロー移行方法があるか?今ここ
Rspec → Schema は rspec-openapi を試している
schema から type 生成は openapi-typescript を試している
生成した schema → type だと、ほとんどが optional の値になってしまって、思った通りに型を使えない。
? をなくしたい。
export interface paths {
'/api/posts': {
get: {
responses: {
200: {
content: {
'application/json': {
id?: number
created_at?: string
updated_at?: string
text?: string
}[]
}
}
}
}
}
}
openapi-typescript のオプションに, defaultNonNullable があるが, true にしても ? になってしまう。
defaultNonNullable のオプションは、defaultNonNullable && default
がある場合になっていたので、rspec-openapi では default の値がないので 全て optional になってしまっているっぽい。
id の default 値とかない気がするから、openapi-typescript の仕様の問題な気もする
また, rspec-openapi では paths のみで components が入ってこないので、type としては使いづらい( type の加工大変)
そもそも流れとして、すでに Rspec があるから自動で schema を生成したいという感じではあるが、schema を生成してそれを使って test するという流れのが一般的っぽい。
確かに Rspec で api インタフェースは手動で記述してるので、そこをなくして schema を手動で書いて、テストするってのもわかるが、 プロジェクトの途中から導入するってケースも多いと思うので、そこまで資産活かして & 段階的に移行する方が良さそうか?
type generate メモ
schema を使ってテストの方法も調べてみる
スキーマを書くことから始める
OpenAPIで記述した仕様をもとにテストを書くことができるようになったわけですが、これを実際の開発フローでどう活用すると良いか考えてみると、
APIの仕様を検討
仕様が決まったらOpenAPIに則ってドキュメントを書く
ドキュメントをもとにしたテストを書く
API実装
組み込みへパス
というのがいいのかなと思いました。
Swagger UI の見た目がなかなかしんどいなぁと思っていたら、
redoc なるものを発見。
デモ
stoplight いいかも。 見た目の swagger ui の 500倍良い。
schema GUIエディタ & 管理ツール + モックサーバー
- schema を spotlight で考える。
- バックエンドは その schema を元に開発 & テスト(comittee など?)
- フロントはその schema を元に type を生成できる
- フロントはそのまま mock サーバーで開発できる
- フロントは cypress などの mock サーバーをバックエンドにできる