Swagger で覚えたこと、ハマったことをメモしていく
Swagger と JSON schema の位置づけ
- Swagger は API を定義するためのもの
- JSON schema は JSON のデータ構造を定義するためのもの
- JSON Hyper-Schema も API を定義するためのもの
対比するとしたら Swagger <-> JSON Hyper-Schema
Swagger <-> JSON schema ではない
現に Swagger の型定義は JSON schema が使われてる
Swagger と JSON Hyper-Schema の比較
Swagger
Pros
- swagger-ui かっこいい
- codegen に言語いっぱい
Cons
- JSON Schema 準拠とはなんだったのか
- JSON Schema の抽出してくれるやつがない
- committee がない
- ドキュメントの通りに実装されていることを保証しようとする何かがないように見える
JSON Hyper-Schema
Pros
- committee がつかえる
- prmd がつかえる
Cons
- generator が heroics くらいしかないのでは
- ref 意味あるのかな...
type を複数指定すると generate client できない
JSON schema と違って type は複数指定できない。
JSON schema を一部採用しているだけで、別に全部取り込んでるわけじゃない。
committee つかいたい
Swagger から型定義ひっこ抜けば理屈上はできるはずだけど、そんなもんなかった。
Swagger から Hyper-Schema に変換するのが楽かと思って適当にスクリプト書いた。
CLI でバリデーションしたい
ないんじゃない?
最初はちょっと変更したら常に確認したい気もしていたけれど、だいたい把握できたらそんなに気にしなくなった。
困ったときに editor に貼ってみる感じ。
http://editor.swagger.io/#/
一方、editor 上で validation 通ってもいい感じのクライアントが生成できるとは限らない。
クライアントの出来は言語ごとにかなりまちまちっぽい?
Angular2 のクライアント生成したい
issue ならあるが本体には入ってない。
issue にコメントされてるやつがいいかも。
動かなかったりしたので直したりした。
プロパティが snake_case でも CamelCase にされるんだけど?
-c をつけて json でなんか設定できるっぽい。
docker run -v $PWD:/tmp swagger-codegen-ng2 generate -i /tmp/swagger.yml -l typescript-angular2 -o /tmp/frontend/app/client -c /tmp/swagger-config.json
{
"modelPropertyNaming": "original"
}