1. 腐らないAPIドキュメントを作る
テストは実装とドキュメントの二人三脚を結ぶ紐
George @uddger

2. 自己紹介
• 髙橋直也 (George) @uddger
• 好きな本「オブジェクト指向設計実践ガイド」
• 「オブジェクト指向設計の理解、優れたリファクタリングスキル、効果的
なテストを書く能力が、3本の柱となって、変更可能なコードを支える」
• 読書100冊/年チャレンジ中
• 今週はよくばりサッカー観戦ウィーク

3. AVA inteligence所属
AVA travel開発
行きたい場所が見つかる旅行サイト

4. APIドキュメント
ある？

5. APIドキュメント、
メンテされてる？

6. よくある解決策
• ドキュメントを書く意識を高めましょう！
• 周りも巻き込みましょう！

7. 続かなくない？仕組みで解決したい💪
• ドキュメントを書く意識を高めましょう？🤔
• 周りも巻き込みましょう？🤔

8. 今日紹介する内容
• 目的
• メンテされ続けるAPIドキュメントを作る
• 手段
• 実装が変わったときに、仕様書も変更しないと落ちるような自動テストを作る
• 利用技術
• RubyGem committee(APIはRails)
• committeeを利用するための準備
• OpenAPI(旧称swagger)形式でAPI仕様書を書いた

9. 入社前、副業して感じた課題
• APIドキュメントはあったりなかったりする
• あってもメンテされないので古くなっていく
• スプレッドシートで、書く人によって違う形式
• エンジニアが増え始めて、バックエンドとフロントエンドの分業体制
が確立しつつあり、調査コストが増えるなど問題が顕在化しつつあっ
た

10. 作った当初は新鮮なドキュメント
ズッ友だよね・・？
実装
ドキュメント

11. 疾走する実装、おいてけぼりのドキュメント
待って・・？
実装
ドキュメント

12. 足を結んでしまえ
実装
ドキュメント

13. 先行する実装に
ドキュメントを食らいつかせろ
実装
ドキュメント

14. 繋ぎ止める紐は、テストだ
実装
ドキュメント
テスト

15. 利用技術：RubyGem committee
• committeeを使用(APIはRails)
• 1行で「OpenAPI形式の仕様書と実装(APIレスポンス)が一致してい
ること」をテストしてくれる。簡単
• 参考記事
• https://gift-tech.co.jp/articles/schema-
fi
rst-api-development/
• https://qiita.com/sakuraya/items/37e73581e90e137b6487
• https://tech.timee.co.jp/entry/2020/07/05/150312#:~:text=OpenAPI3%E3%81%AErequired%E3%81%AB%E6%B3%A8%E6%84%8F%E3%81%99%E3%82%8B
• https://zenn.dev/offers/articles/20220411-open-api-schema

16. 準備：OpenAPI(旧称swagger)形式のAPI仕様書
• API schemaをYaml/JSONで管理する
• デファクトスタンダードになりつつある
• 副次的なメリット
• フォーマットの属人化を防げた
• Git管理できて差分が追える
• 手軽に高機能な仕様書が作れてめっちゃ便利
• スキーマ駆動になって、スタブAPIも作れるから、バックエンドとフロントエンドの開発順番の依存
関係が軽減される

17. 費用対効果の高いテストを目指したい
• カバレッジ100%は目指さない(目指せない)
• スタートアップということもあり、そのリソースがあれば機能開発
に使う
• 導入2ヶ月目、体感でカバレッジは20%程度だけどこれでいい
• 既存の重要機能/新機能から頑張る
• かける時間を回収可能な、よく変更する機能を見極める

18. ありがとうございました！
@uddger