Post on 23-Jan-2018
株式会社Emotion Tech三上 悟
WebAPI開発に必要なドキュメントを作る話
第２回 人形町Techで騒がNight♥
会社紹介
株式会社Emotion Tech（旧 wizpra)
ミッション「すべての人がイキイキと働ける社会の実現」
事業内容顧客の声を起点とした経営課題の解決
サービス品質の向上を行うサービス
「Emotion Tech」の開発・運営
サービス紹介
“Emotion Tech”は、顧客・従業員の感情データをリアルタイムに集計・定量的に分析・可視化できる、ロイヤルティ向上支援クラウドシステム
簡単に説明すると・・・
アンケートに回答して 回答を分析すると
商品の推奨度がわかる改善点がわかる改善提案ができる
自己紹介
三上 悟 @saicologic
所属：株式会社Emotion Tech 2017年3月入社。主にバックエンド側のエンジニアです。
最近は、分析基盤とWebAPIを作ってます。
Docker、Embulk、Digdag、AngularR、Python、Ruby、SQL、TypeScriptAWS
WebAPI開発に必要なドキュメントを作る話
課題
Front Side(Angualr)
Server Side(Rails + grape)
ここのドキュメントをどうやって管理するか？
現状
Excelで管理されています
・１シートに行列で管理されている
・人手で記述しているため、ソースコードとAPIドキュメントに差異がある
・APIドキュメントが最新版であることが保証されていない
開発はモダンなのに、ここだけレガシー！？
利便性
・ドキュメントを管理したくないから、ソースコードから自動生成して欲しい
・開発中のWebAPIのドキュメントも欲しい
汎用性
・言語が変わってもドキュメントの生成方法は同じにしたい
可読性
・リクエストの必須パラメータ／オプションが知りたい
・パラメータの意味が知りたい
・実行せずともレスポンスの結果が知りたい
・ドキュメントだけでなく実際に仮のデータで見たい
利用制限
・外部提供用のドキュメントも欲しい
欲しいもの
調査対象サービス／ツール 5種
・Apiary
・Swagger
・apidoc
・iodocs
・autodocs
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)
Apiary
https://app.apiary.io/demo547/editor
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には対応していない
Swagger
https://app.swaggerhub.com/apis/ldrozdz/Messaging-Redux/current
・オープンソース（Node.js）
・ソースコード内に独自記法で記述する
APIDOC Inline Documentation for RESTful web APIs
iodocs Interactive API documentation system
・オープンソース（Node.js)・JSONで記述する
iodocs
http://localhost:3000/foursquare
autodocs Generate documentation from your rack application & request-spec.
・オープンソース
・rspecからMarkdown形式でドキュメントを自動生成する
autodocs
https://github.com/r7kamura/autodoc/blob/master/spec/dummy/doc/recipes.md
比較表
サービス／ツール名 WebMock API Spec ドキュメント作成補助
SaaS
Apiary ○ Blueprint(Markdown) ○ ○
Swagger ○ Swagger Spec(JSON or YAML) ○ ○
apidoc × apidoc(コード内コメント） × ×
iodocs ○ JSON × ×autodocs × Ruby
(rspec) ○ ×
・Web Mockが欲しい => Apiary or Swagger or iodocs
・ドキュメント作成補助が欲しい
=> Apiary or Swagger
ApiaryとSwaggerのどちらにするか？
どれを選ぶか
API Spec 比較
Last updated November 4, 2016
API Spec Comparison Tool
Google Trends
Open API Initiative
ORACLE vs Open Community
オススメは、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が見れる