GolangでAPIドキュメント自動生成

社内LT

Transcript

1. GolangでAPIドキュメント自動 生成 2017/11/17 飯野 雅希
2. APIドキュメント書いてますか？
3. APIドキュメントは書くのが大変 • Host • Path • HTTPメソッド • Request Header, Body • Query Parameter • Response Status Code • Response Header, Body • etc...
4. 書き手と読み手が違う • 書くのはサーバーエンジニア • 読むのはフロント・クライアントエンジニア
5. APIドキュメンテーションツール • Swagger • apiblueprint
6. API Blueprint • Markdownを使って定義を書く ◦ 拡張子は.apib • Markdownそのままでも読みやすい
7. API Blueprint • 基本情報 ◦ タイトル ◦ ホスト • グループ • endopoint情報 ◦ HTTPメソッド ◦ endpoint ◦ リクエスト ◦ パラメータ ◦ レスポンス
8. 読みやすく高機能
9. だけど、手書きで管理し続けるのは大変
10. ドキュメントを自動生成しよう 要件 • Golangでコード書いたらapiblueprintでドキュメント自動生成 • apibファイルだとviewerがいるので、HTMLに変換
11. apiblueprint生成 test2doc：https://github.com/adams-sarah/test2doc • GolangのPackage • Star 236 • Unitテストと組み合わせると自動でAPIドキュメントを生成してくれる
12. test2doc
13. test2doc
14. HTMLに変換 Gulpスクリプトで変換 https://storage.googleapis.com/iino-test-api-doc-test/out.html
15. 所感 • 自動で生成されるのでコードとドキュメントの乖離がなくなる • Go lint/vet でタイポも防げる • 楽できる