API Documentを自動生成してくれるツール「Swagger」をScalaで導入検証してみた結果…

1. Good-Bye

2. Introduction
Name
片田

3. What is Swagger?
http://swagger.io/
Swagger
- [形容詞]((略式))しゃれた、めかした、いきな

4. What is Swagger?
コードからAPI Documentを
自動生成してくれる粋なツール！

5. What is Swagger?
いちいちドキュメントを書く必要がない！
APIに変更があった時(カラムが増えた時など)に
ドキュメントを編集する必要もない！

6. Swaggerツール
1. Swagger Core
– Swaggerのメインリポジトリー
2. Swagger UI
– SwaggerのUI部分, Swagger APIを元に生成する

7. Swaggerツール
今回は、Play Framework用のSwaggerライブラリを使いました。
※かつてはSwagger CoreリポジトリにPlay Frameworkのライブラリもあったようだが、
現在はSwagger-Playリポジトリに移動している

8. Scalaのコードの中にSwaggerの記述をする
Swaggerツール
Scalaが生成したJSONを元にSwagger UIが生成される

9. Swaggerツール
必要なこと
1. Play Frameworkの場合routesにSwaggerのDocs用のURLを記述する
1. SwaggerのAnnotationをコントローラ に(場合によってはモデルにも)記述する

10. Swaggerツール
スーパーシンプル！

11. Swagger
ウキウキ気分で1日かけてSwagger導入のためコードを書いた
その結果、、、

12. Swagger
あまり使えない。

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

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

15. 問題その２
Genericsを使うとnull値が入る。

16. 問題その２
Null値が入ってしまう。

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

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

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