WebAPI開発に必要な ドキュメントを作る話

1. 株式会社Emotion Tech
三上 悟
WebAPI開発に必要な
ドキュメントを作る話
第２回 人形町Techで騒がNight♥

2. 会社紹介
株式会社Emotion Tech（旧 wizpra)
ミッション
「すべての人がイキイキと働ける社会の実現」
事業内容
顧客の声を起点とした経営課題の解決
サービス品質の向上を行うサービス
「Emotion Tech」の開発・運営

3. サービス紹介
“Emotion Tech”は、顧客・従業員の感情データをリアルタイムに
集計・定量的に分析・可視化できる、ロイヤルティ向上支援クラウドシステム

4. 簡単に説明すると・・・
アンケートに回答して 回答を分析すると
商品の推奨度がわかる
改善点がわかる
改善提案ができる

5. 自己紹介
三上 悟 @saicologic
所属：株式会社Emotion Tech
2017年3月入社。主にバックエンド側のエンジニアです。
最近は、分析基盤とWebAPIを作ってます。
Docker、Embulk、Digdag、Angular
R、Python、Ruby、SQL、TypeScript
AWS

6. WebAPI開発に必要な
ドキュメントを作る話

7. 課題
Front Side
(Angualr)
Server Side
(Rails + grape)
ここのドキュメントをどうやって管理するか？

8. 現状
Excelで管理されています
・１シートに行列で管理されている
・人手で記述しているため、ソースコードとAPIドキュメントに差異がある
・APIドキュメントが最新版であることが保証されていない

10. 開発はモダンなのに、ここだけレガシー！？

11. 利便性
・ドキュメントを管理したくないから、ソースコードから自動生成して欲しい
・開発中のWebAPIのドキュメントも欲しい
汎用性
・言語が変わってもドキュメントの生成方法は同じにしたい
可読性
・リクエストの必須パラメータ／オプションが知りたい
・パラメータの意味が知りたい
・実行せずともレスポンスの結果が知りたい
・ドキュメントだけでなく実際に仮のデータで見たい
利用制限
・外部提供用のドキュメントも欲しい
欲しいもの

12. 調査対象サービス／ツール 5種
・Apiary
・Swagger
・apidoc
・iodocs
・autodocs

13. Apiary
・SaaS型のドキュメント管理サービス
・APIドキュメントは、Blueprint（Markdown）で記述する
・Swagger Specにも対応している
・ドキュメントの生成と同時にAPIのモックサーバーが用意される
・SaaSで利用することができる
・Private/Teamで利用する場合は、$99~
・オープンソースでツールが提供されている
・API Blueprint
・dredd( HTTP Testing Framework )
・Apiary CLI
・Snow Crash( API Blueprint Parser)
・aglio (API Blueprint Renderer)

14. Apiary
https://app.apiary.io/demo547/editor

15. Swagger
・SaaS型のドキュメント管理サービス
・APIドキュメントは、Swagger Spec（JSON or YAML）で記述する
・ドキュメントの生成と同時にAPIのモックサーバーが用意される
・SaaSで利用することができる（Swagger Hubと呼ばれている）
・Private/Teamで利用する場合は、$49~
・オープンソースでツールが提供されている
・Swagger Editor
・Swagger Codegen
・Swagger UI
・SwaggerHub(Swagger Editor + Swagger UI)
・Apiary Blueprintには対応していない

16. Swagger
https://app.swaggerhub.com/apis/ldrozdz/Messaging-Redux/current

17. ・オープンソース（Node.js）
・ソースコード内に独自記法で記述する
APIDOC Inline Documentation for RESTful web APIs

18. APIDOC
http://apidocjs.com/example/

19. iodocs Interactive API documentation system
・オープンソース（Node.js)
・JSONで記述する

20. iodocs
http://localhost:3000/foursquare

21. autodocs Generate documentation from your rack application & request-spec.
・オープンソース
・rspecからMarkdown形式でドキュメントを自動生成する

22. autodocs
https://github.com/r7kamura/autodoc/blob/master/spec/dummy/doc/recipes.md

23. 比較表
サービス／ツール名 WebMock API Spec
ドキュメント
作成補助
SaaS
Apiary ○ Blueprint
(Markdown) ○ ○
Swagger ○ Swagger Spec
(JSON or YAML) ○ ○
apidoc × apidoc
(コード内コメント） × ×
iodocs ○ JSON × ×
autodocs × Ruby
(rspec) ○ ×

24. ・Web Mockが欲しい
=> Apiary or Swagger or iodocs
・ドキュメント作成補助が欲しい
=> Apiary or Swagger
ApiaryとSwaggerのどちらにするか？
どれを選ぶか

25. API Spec 比較
Last updated November 4, 2016
API Spec Comparison Tool

26. Google Trends

27. Open API Initiative

28. ORACLE vs Open Community

29. オススメは、Swagger
・Google TrendsだとSwagger
・オープンの方が扱いやすい
・ツールが充実しているため、Swaggerのほうが良さそう
・swagger-editor Web Editor
・swagger-ui Web UI
・ruby-swagger APISpec(swagger.json)の自動生成
・swagger-rb APISpecのParser
・grape-swagger grapeを使っている場合、swagger-uiが見れる