swagger

Swagger についての覚書

More than 3 years have passed since last update.

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 を一部採用しているだけで、別に全部取り込んでるわけじゃない。

https://github.com/swagger-api/swagger-editor/issues/868#issuecomment-210019159


committee つかいたい

Swagger から型定義ひっこ抜けば理屈上はできるはずだけど、そんなもんなかった。

Swagger から Hyper-Schema に変換するのが楽かと思って適当にスクリプト書いた。

https://github.com/mtsmfm/swagger2hyperschema


CLI でバリデーションしたい

ないんじゃない?

最初はちょっと変更したら常に確認したい気もしていたけれど、だいたい把握できたらそんなに気にしなくなった。

困ったときに editor に貼ってみる感じ。

http://editor.swagger.io/#/

一方、editor 上で validation 通ってもいい感じのクライアントが生成できるとは限らない。

クライアントの出来は言語ごとにかなりまちまちっぽい?


Angular2 のクライアント生成したい

issue ならあるが本体には入ってない。

https://github.com/swagger-api/swagger-codegen/issues/1809

issue にコメントされてるやつがいいかも。

https://github.com/sapienstech/typescript-angular2-swagger-codegen/

動かなかったりしたので直したりした。


プロパティが 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"
}