good-bye swagger

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

あまり使えない。

問題その１

Option[Int]/Option[Boolean] 　などのOption プリミティブ型が Swagger UI 上に表示されない！元のコードが Java だから Option は何かのオブジェクトとしか認識されないのかも、、、

問題その１

解決策モデルで ApiModel で dataType( 型 ) を毎回指定する→ 完全な自動生成じゃない。

問題その２

Generics を使うと null 値が入る。

問題その２

Null 値が入ってしまう。

その他問題

https に完全対応してない。Map 型対応してない。日本語ドキュメント少ない。Swagger Annotation のドキュメント極少。やや重い。

結論バグ ( 仕様 ?) に取られる工数を考えると普通にドキュメント書いた方が早い。

ご静聴ありがとうございました。Swagger - (( 古風 )) (… について ) おおぼらをふく