APIドキュメントの光と闇

APIStudy #11での登壇資料です。

https://apistudy.connpass.com/event/62970/

Transcript

1. APIドキュメントの 光と闇 MOONGIFT 中津川篤司 2017.08.29 APIStudy #11
2. 自己紹介 2 !HPPGNJOU GCNFHPPGNJOU த௡઒
   ಞ࢘ גࣜձࣾ.00/(*'5
   ୅දऔక໾ 4RVBSF
   
   /$.#ͷ%FW3FMΛαϙʔτத ೥݄ΑΓΦʔϓϯιʔεɾιϑτ΢ΣΞΛຖ ೔঺հ͢Δϒϩά
   .00/(*'5
   ΛӡӦɻ IUUQXXXNPPOHJGUKQ
3. 本日の目標
4. େࣄͳ͓࢓ࣄ 4RVBSF
   ɺ"1*ެ։ͯ͠ ΔΜͩͬͯʂ
   BQJTUVEZ
5. 4RVBSFʁ
7. APIドキュメント 大事ですよね！
8. ドキュメントの要望 開発者側 提供側 記載ミスがない 記載ミスがない 読みやすい メンテナンスが容易 分かりやすい 多言語対応 多言語対応 システム連携 検索性
9. ドキュメントの形式 システム連携型 静的HTML型 Wiki型
10. システム連携 HTMLドキュメント Swagger.json コード + DSL
11. class PetsController < ActionController::Base include Swagger::Blocks swagger_path '/pets/{id}' do operation :get do key :summary, 'Find Pet by ID' key :description, 'Returns a single pet if the user key :operationId, 'findPetById' key :tags, [ 'pet' ] parameter do key :name, :id key :in, :path key :description, 'ID of pet to fetch' key :required, true key :type, :integer key :format, :int64 end response 200 do
12. DSLの光 コードの近くにドキュメントが書ける メンテナンスが容易 網羅性が高い
13. DSLの闇 ファイルサイズが増えがち コードの可読性が落ちる サンプルコードとか書き出すと 目も当てられない… 多言語対応？何それ、おいしいの？
14. 静的サイト型 Jekyll MkDocs Slate Daux.io Nanoc
15. 機能 静的HTML出力 GitHub Pages対応 Markdownで記述
16. 静的サイトの光 API以外（チュートリアルなど）も 含めて記述できる 多言語対応 自由度の高さ
17. 静的サイトの闇 網羅性の低さ メンテナンス工数高 多言語対応時の工数高
18. 個人的な解決策 MkDocs + Swagger.json + GetText + スクリプト Swagger.json でスクリプト（Ruby）を使って Markdownファイルを生成。GetTextで多言語化 も。
19. Squareの場合 社内サービスはProtocol Bufferで実装 Protocol Bufferの定義 → Java → Swagger.json Swagger.jsonをHTMLドキュメント化 現在英語版のみ さらにSwagger.json → Swagger Codegen → SDK生成 https://www.slideshare.net/tristansokol/sdks-the-good-the-bad-the-ugly-japan
21. まとめ コードとドキュメントの乖離がなくて、 メンテナンスしやすく、分かりやすくて 多言語対応できるドキュメントの仕組みっ て実現できないだろうか。