株式会社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

APIDOC

http://apidocjs.com/example/

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が見れる