Apiドキュメントの話 in SphinxCon JP 2015

1. APIドキュメントのはな
し
小宮健 (Takeshi KOMIYA) @tk0miya
SphinxCon JP 2015

2. Who am I ?
 仕事
 (株)タイムインターメディア所属
 Commiter of Sphinx
 Mr. Sphinx Extension Generator
 Communities:
 Sphinx-users.jp
 Sphinx+翻訳 Hack-a-thon
 毎月開催しています (Every month!)
 Watch http://sphinxjp.connpass.com/
Twitter: @tk0miya

3. Who am I ?
 blockdiag というツールを作ってます
 テキスト(DSL like .dot)から画像を生成し
ます{
トップページ -> ログイン -> マイペー
ジ;
トップページ -> 商品一覧 -> 商品詳細;
}

4. Who am I ? (Books, Articles)
 Sphinx 関連の書籍、記事を書いています
 Sphinx をはじめよう
 Software Design 2015/12月号 (来月もね！)

5. 近況
 最近は Rails プロジェクトで仕事をしてい
ます
 …がコードを書けていません
 少し前まで Web API の設計をしていまし
た
 API の定義を書くだけのかんたんなお仕事
 (I designed API docs in nearest job)

6. Web API の設計
 Web API I/F 定義って何で書きます？
 WSDL (Web Service Description Lang)
 WADL (Web Application Description Lang)
 RADL (RESTful A1PI Description Lang)
 JSON Hyper Schema
 Swagger
 RAML (RESTful API Modeling Lang)
 API Blueprint (markdown)

7. Web API の設計 / Designing Web API
 最初は JSON Schema を考えた
 Heroku の Platform API でも使っているし…
 実際に試してみると…？
 大量に定義しようとするとだるい (very tired…)
 あれはコンピュータが解釈するもの(hard to
write)
 もっと手軽に書ける文法が欲しい… (hard
syntax)
 ということで
 API Blueprint を利用することにしました

8. API Blueprint
 Web API Language (Markdown based)
 色んなものに変換できる
 HTML
 mock API server
 Client libs
 JSON Schema
 様々なツールが対応し(はじめ)ている
 More details: see apiblueprint.org

9. API Blueprint
# GET /message
+ Response 200 (text/plain)
Hello World!

10. API Blueprint のメリット / Merit
 オープンなフォーマットである (Open
Format)
 見た目がきれい (Cool outputs)
 さっくり書いて共有するには悪くない
(EasyUse)

11. API Blueprint のデメリット (1) / Demerit
 実装レベルはツールによってまちまち
 apiary.io は実装がしっかりしている
 Web サービスなのでクローズドな内容には使いづら
い
 OSS である aglio は対応してない機能がある
 他のツールはまだ枯れていない感じ

12. API Blueprint のデメリット (2) / Demerit
 他のドキュメントと連携しづらい
 システムの全体像を書いたり…
 API の主要シーケンスを書いたり…
 拡張が使えなかったり…
 blockdiag とかね :-)
 それ Sphinx でできるよ！
 と思って Sphinx 拡張を書いてみました。

13. Sphinx meets API Blueprint
 sphinxcontrib-blueprint
 NEWEST sphinx extesion in the world
 Released at 20:00 (JST)
 総開発期間 2日
 This is concept release :-p

14. How to use sphinxcontrib-apiblueprint
 Install
 How to use
.. apiblueprint:: [filename]
pip install sphinxcontrib-apiblueprint

15. Demo
 デモします。

16. 現時点での問題点
 見づらい (not cool )
 API を :ref: できない (do not refer API)
 Github Flavored Markdown を解釈できない
 内部では commonmark としてパース
 テーブル記法が使えない！
 未対応の記法がある
 (does not support any notation)

17. Next step
 まずは完成させる 
 (implement more)
 その次は Sphinx っぽいアレンジを
 (make it more Sphinx-ish)

18. Sphinx っぽいアレンジ / Sphinx-ish?
 入力 / Input
 Support more format(swagger, JSON Schema)
 構造化 / Structuring
 httpdomain
 Combination with extensions
 出力 / Output
 More cool design!

19. まとめ
 API Blueprint を使ってみました
 sphinxcontrib-apiblueprint を作りました
 改善しようと思っています
 興味がある人いませんか