good-bye swagger
TRANSCRIPT
Good-Bye
Introduction
Name
片田
What is Swagger?http://swagger.io/
Swagger - [ 形容詞 ](( 略式 )) しゃれた、めかした、いきな
What is Swagger?
コードから API Document を自動生成してくれる粋なツール!
What is Swagger?
いちいちドキュメントを書く必要がない!API に変更があった時 ( カラムが増えた時など ) にドキュメントを編集する必要もない!
Swagger ツール
1. Swagger Core – Swagger のメインリポジトリー
2. Swagger UI – Swagger の UI 部分 , Swagger API を元に生成する
Swagger ツール
今回は、 Play Framework 用の Swagger ライブラリを使いました。
※ かつては Swagger Core リポジトリに Play Framework のライブラリもあったようだが、現在は Swagger-Play リポジトリに移動している
Scala のコードの中に Swagger の記述をする
Swagger ツールScala が生成した JSON を元に Swagger UI が生成される
Swagger ツール
必要なこと1. Play Framework の場合 routes に Swagger の Docs 用の URL を記述する
2. Swagger の Annotation をコントローラ に ( 場合によってはモデルにも ) 記述する
Swagger ツール
スーパーシンプル!
Swagger
ウキウキ気分で 1 日かけて Swagger 導入のためコードを書いたその結果、、、
Swagger
あまり使えない。
問題その1
Option[Int]/Option[Boolean] などのOption プリミティブ型が Swagger UI 上に表示されない!元のコードが Java だから Option は何かのオブジェクトとしか認識されないのかも、、、
問題その1
解決策モデルで ApiModel で dataType( 型 ) を毎回指定する→ 完全な自動生成じゃない。
問題その2
Generics を使うと null 値が入る。
問題その2
Null 値が入ってしまう。
その他問題
https に完全対応してない。Map 型対応してない。日本語ドキュメント少ない。Swagger Annotation のドキュメント極少。やや重い。
結論バグ ( 仕様 ?) に取られる工数を考えると普通にドキュメント書いた方が早い。
ご静聴ありがとうございました。Swagger - (( 古風 )) (… について ) おおぼらをふく