APIドキュメントの話 #sphinxjp

4,684 views

Published on

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

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,684
On SlideShare
0
From Embeds
0
Number of Embeds
2,935
Actions
Shares
0
Downloads
3
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide
  • This is example of blockdiag.
    Connect nodes with arrow operator.

    After execute blockdiag command, you can get images.
  • This is example of blockdiag.
    Connect nodes with arrow operator.

    After execute blockdiag command, you can get images.
  • APIドキュメントの話 #sphinxjp

    1. 1. APIドキュメントのはな し 小宮健 (Takeshi KOMIYA) @tk0miya SphinxCon JP 2015
    2. 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. 3. Who am I ?  blockdiag というツールを作ってます  テキスト(DSL like .dot)から画像を生成し ます{ トップページ -> ログイン -> マイペー ジ; トップページ -> 商品一覧 -> 商品詳細; }
    4. 4. Who am I ? (Books, Articles)  Sphinx 関連の書籍、記事を書いています  Sphinx をはじめよう  Software Design 2015/12月号 (来月もね!)
    5. 5. 近況  最近は Rails プロジェクトで仕事をしてい ます  …がコードを書けていません  少し前まで Web API の設計をしていまし た  API の定義を書くだけのかんたんなお仕事  (I designed API docs in nearest job)
    6. 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. 7. Web API の設計 / Designing Web API  最初は JSON Schema を考えた  Heroku の Platform API でも使っているし…  実際に試してみると…?  大量に定義しようとするとだるい (very tired…)  あれはコンピュータが解釈するもの(hard to write)  もっと手軽に書ける文法が欲しい… (hard syntax)  ということで  API Blueprint を利用することにしました
    8. 8. API Blueprint  Web API Language (Markdown based)  色んなものに変換できる  HTML  mock API server  Client libs  JSON Schema  様々なツールが対応し(はじめ)ている  More details: see apiblueprint.org
    9. 9. API Blueprint # GET /message + Response 200 (text/plain) Hello World!
    10. 10. API Blueprint のメリット / Merit  オープンなフォーマットである (Open Format)  見た目がきれい (Cool outputs)  さっくり書いて共有するには悪くない (EasyUse)
    11. 11. API Blueprint のデメリット (1) / Demerit  実装レベルはツールによってまちまち  apiary.io は実装がしっかりしている  Web サービスなのでクローズドな内容には使いづら い  OSS である aglio は対応してない機能がある  他のツールはまだ枯れていない感じ
    12. 12. API Blueprint のデメリット (2) / Demerit  他のドキュメントと連携しづらい  システムの全体像を書いたり…  API の主要シーケンスを書いたり…  拡張が使えなかったり…  blockdiag とかね :-)  それ Sphinx でできるよ!  と思って Sphinx 拡張を書いてみました。
    13. 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. 14. How to use sphinxcontrib-apiblueprint  Install  How to use .. apiblueprint:: [filename] pip install sphinxcontrib-apiblueprint
    15. 15. Demo  デモします。
    16. 16. 現時点での問題点  見づらい (not cool )  API を :ref: できない (do not refer API)  Github Flavored Markdown を解釈できない  内部では commonmark としてパース  テーブル記法が使えない!  未対応の記法がある  (does not support any notation)
    17. 17. Next step  まずは完成させる   (implement more)  その次は Sphinx っぽいアレンジを  (make it more Sphinx-ish)
    18. 18. Sphinx っぽいアレンジ / Sphinx-ish?  入力 / Input  Support more format(swagger, JSON Schema)  構造化 / Structuring  httpdomain  Combination with extensions  出力 / Output  More cool design!
    19. 19. まとめ  API Blueprint を使ってみました  sphinxcontrib-apiblueprint を作りました  改善しようと思っています  興味がある人いませんか

    ×