仕事で教えてもらったので、忘れないようにメモ。
概要
quicktypeのサイトにjsonを貼り付けると、自動で定義が生成される。
すごいシンプルなので、操作説明すら不要。
メインターゲット層
- 非エンジニアの現場とやり取りしたいエンジニア
- sampleJsonを提示されてTypescriptに移行するリプレイス案件
- 非公開定義を定義化したい
- API定義書を新規作成する
これを使った経緯
会社にばれても怒られないと思いますが…。
一応、以下のは「例」ということでお願いします。
基本的に開発者だけで作成するときは、Swagger等で先にAPI定義書を作成し、影響のあるシステムに先行公開しておくことでコミュニケーションをとるかと思います。
が、非エンジニアにはyamlやjsonでの管理は重い。
(エンジニアでも、yamlだけはしんどいと思います)
CMSを使っている非エンジニアの部署では、公開物の管理をExcel(kintone)で管理していた。
そのExcelをもとにjsonを吐き出すスクリプトを使用し、そのjsonを元にCMSで商品を表示できるようにしていた。
CMSをリプレイスするにあたり、自分たちの部署に依頼が入りました。
ちょうどTypescriptを使いたかったので、安全に開発できるように、型定義から作成しようした。
Excelで定義を確認すれば型定義も作成できた。
しかし、複数のシートにまたがっていたり、多重度がExcel上ではわかりづらい…。
等々、定義を作るだけで数日の工数が持っていかれるなど非効率極まりない状況。
そういう状況下で、既に出力されているjsonを元にTypescriptの型定義を作成できるサイトを教えてもらいました。
使ってみて、工数削減につながったので紹介しています。
まぁ、この案件から外されちゃって、生成物がどこまで信用できるか、という点は分かりません。
1回えいやっと、作成し、そのあと細かいメンテナンスは手動になるんじゃないでしょうか。
ソースコード
CLIもあるようです。
上記サイトを使用したことによる情報流出を恐れている場合、こちらからダウンロードしたほうがいいかも。
GitHub
変換前/変換後のフォーマット
変換前
- JSON
- JSON API URLs
- JSON Schema
- TypeScript
- GraphQL queries
- Postman v2.1
- Githubには書いてませんでしたが、サイトにはありました
あと、GoogleのSpreadSheetも使えそうですね。
サイトには書いてありましたが、これは使ったことないので、わかりません。
変換後
大量にあるので、公式から確認してください。
これを元に、Json Schemaを再生成できるのは面白いですね。
個人的にはJavaとTypescriptが使用できる点は好きです。
感想
個人的には今後積極的に機会はないかとは考えてます。
なぜなら、生成されるのは型定義だけで、それを取得するAPIまでは自動生成してくれない認識だからです。
APIも含めて自動生成したい、ということになると結局従来通りSwaggerを使っていると思いますので…。
リプレイス等で過去にyamlやjsonでのAPI定義書を作っていない。
ということであれば、ここでjson schemaを生成して、Swaggerに再度食べさせるのはあり…ですかね。
正直、型定義を作るところまでしか使用してないので、quicktypeの強みは完全にわかっていません。
もし、異論・追加等がありましたら、はてブやコメントにて直接書いていただけると助かります。